@eyeauras/insight-cli 0.3.2 → 0.4.0

package/dist/src/contexts.js

@@ -1,3 +1,4 @@
+import { recordLifecycle } from './context-diagnostics.js';
 import { ghidraBudget } from './budgets.js';
 import { launchProcess, terminateProcess } from './tool-runtime/supervisor.js';
 import { runTool } from './tool-runtime/run.js';
@@ -11,7 +12,7 @@ import { createServer } from 'node:net';
 import { setTimeout as delay } from 'node:timers/promises';
 import { nativeHelpers, nativeInputs, nativeJvmDirectories, nativeExtensionArguments } from './native-inputs.js';
 import { GhidraServer } from './server.js';
-import { object, fail, text, version, stable } from './model.js';
+import { object, fail, text, version, stable, digest } from './model.js';
 import { HttpBridge } from './transport.js';
 import { scriptInventory, scriptPath } from './scripts.js';
 import { logicalPrograms } from './cross-results.js';
@@ -21,6 +22,8 @@ import { readCallerGoal, awaitCaller } from './debugger-caller.js';
 import { debuggerProgramMetadata } from './debugger-results.js';
 import { nativeQueries } from './query-policy.js';
 import { nativeQuery } from './native-queries.js';
+import { runInline } from './inline-script.js';
+import { researchView } from './research-view.js';
 import { sdkWrites } from './sdk-contracts.js';
 import { initialIntent, initializeModel } from './initial-model.js';
 import { managedGhidraDebugger, prepareGhidraDebugger } from './ghidra-debugger-runtime.js';
@@ -149,6 +152,8 @@ export class GhidraContexts {
                     const info = await record.http.instance();
                     if (info.pid !== binding.pid || info.tcp_port !== endpointPort)
                         fail('binding', 'Context endpoint belongs to a different native process.');
+                    if (context)
+                        await recordLifecycle(this.workspace, context, { at: new Date().toISOString(), event: 'start', reason: 'native_launch', pid: binding.pid });
                     return record;
                 }
                 catch {
@@ -162,6 +167,11 @@ export class GhidraContexts {
                 child.kill('SIGTERM');
             for (let i = 0; i < 100 && child.exitCode === null && child.signalCode === null; i++)
                 await delay(50);
+            if (context && (child.exitCode !== null || child.signalCode !== null)) {
+                const at = new Date().toISOString();
+                await durable(join(root, 'stopped.json'), { pid: binding.pid, tokenSecret: binding.tokenSecret, at, reason: 'startup_failed' });
+                await recordLifecycle(this.workspace, context, { at, event: 'stop', reason: 'startup_failed', pid: binding.pid });
+            }
             this.running.delete(root);
             throw error;
         }
@@ -190,7 +200,7 @@ export class GhidraContexts {
             fail('binding', 'Opened native program does not match the target input bytes.');
         return object(await record.http.call('/get_metadata', { program: record.binding.program }));
     }
-    async stopRecord(record, ready = true, releaseCapacity = true) {
+    async stopRecord(record, ready = true, releaseCapacity = true, reason = 'temporary_complete') {
         const { binding, child } = record;
         const childFinished = child && child.pid === binding.pid && (child.exitCode !== null || child.signalCode !== null);
         if (!childFinished && alive(binding.pid)) {
@@ -213,7 +223,10 @@ export class GhidraContexts {
         }
         if (binding.mode === 'gui')
             await this.debuggerReleased(binding);
-        await durable(join(binding.root, 'stopped.json'), { pid: binding.pid, tokenSecret: binding.tokenSecret });
+        const at = new Date().toISOString();
+        await durable(join(binding.root, 'stopped.json'), { pid: binding.pid, tokenSecret: binding.tokenSecret, at, reason });
+        if (binding.context)
+            await recordLifecycle(this.workspace, binding.context, { at, event: 'stop', reason, pid: binding.pid });
         if (releaseCapacity && binding.context)
             this.capacity.slots.delete(binding.context);
         this.running.delete(binding.root);
@@ -378,11 +391,13 @@ export class GhidraContexts {
             record.binding.viewEpoch = context.viewEpoch ?? 0;
             await durable(join(root, 'process.json'), record.binding);
             await durable(join(this.directory(), 'context', context.id, 'current.json'), record.binding);
+            if (context.workingSnapshot)
+                await recordLifecycle(this.workspace, context.id, { at: new Date().toISOString(), event: 'restore', reason: 'saved_snapshot', pid: record.binding.pid });
             return record;
         }
         catch (error) {
             if (record)
-                await this.stopRecord(record, false);
+                await this.stopRecord(record, false, true, 'startup_failed');
             else
                 this.capacity.slots.delete(context.id);
             throw error;
@@ -413,7 +428,7 @@ export class GhidraContexts {
         }
         if (binding && !stopped && alive(binding.pid) && ((binding.viewEpoch ?? 0) !== (context.viewEpoch ?? 0) ||
             binding.baseRevision !== context.baseRevision && context.baseRevision !== undefined)) {
-            await this.stopRecord(await this.verified(binding, target), true, false);
+            await this.stopRecord(await this.verified(binding, target), true, false, 'view_replaced');
             stopped = true;
         }
         if (binding && !stopped && alive(binding.pid)) {
@@ -434,6 +449,8 @@ export class GhidraContexts {
         const snapshot = context.workingSnapshot ?? model.sharedSnapshot;
         if (!snapshot || !model.sharedRevision)
             fail('binding', 'Canonical target has no saved base.');
+        if (binding && !stopped && !alive(binding.pid))
+            await recordLifecycle(this.workspace, context.id, { at: new Date().toISOString(), event: 'stop', reason: 'unknown', pid: binding.pid });
         await this.privateCopy(context, snapshot);
         if (context.workingSnapshot)
             return this.workspace.saveContext(scope, context.generation, { state: 'ready' });
@@ -447,7 +464,19 @@ 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 observation(scope) {
+        const record = await this.selected(scope);
+        return { ...object(await this.call(scope, '/research_view')), incarnation: digest({ pid: record.binding.pid, root: record.binding.root }) };
+    }
+    async inspectObservation(scope) {
+        const record = await this.selected(scope);
+        const view = researchView(await record.http.call('/insight/research-view/v1', { program: record.binding.program }));
+        return { ...view, incarnation: digest({ pid: record.binding.pid, root: record.binding.root }) };
+    }
+    async inlineScript(scope, parameters, requestId) {
+        const record = await this.selected(scope);
+        return runInline(record.http, record.binding.program, record.binding.root, parameters, requestId);
+    }
     async call(scope, operation, parameters = {}) {
         if (Object.hasOwn(parameters, 'program'))
             fail('invalid', 'Program routing is owned by the session and target selectors.');
@@ -652,7 +681,7 @@ public class ${name} extends GhidraScript {
         const debuggerState = record.binding.mode === 'gui' && context.debugger?.traces.length ? await this.debuggerSaved(scope) : context.debugger;
         const complexChanges = await this.debuggerMetadataChanges(context, snapshot);
         this.workspace.saveContext(scope, context.generation, { workingSnapshot: snapshot, complexChanges, ...(debuggerState ? { debugger: { ...debuggerState, connected: false, traces: debuggerState.traces.map(trace => ({ ...trace, connected: false })) } } : {}) });
-        await this.stopRecord(record, true, false);
+        await this.stopRecord(record, true, false, 'mode_changed');
         if (mode === 'headless') {
             await this.privateCopy(this.workspace.context(scope), snapshot);
             return;
@@ -868,7 +897,7 @@ public class ${name} extends GhidraScript {
         const debuggerState = record.binding.mode === 'gui' && context.debugger?.traces.length ? await this.debuggerSaved(scope) : context.debugger;
         const complexChanges = await this.debuggerMetadataChanges(context, snapshot);
         this.workspace.saveContext(scope, context.generation, { state: 'stopped', workingSnapshot: snapshot, complexChanges, ...(debuggerState ? { debugger: { ...debuggerState, connected: false, traces: debuggerState.traces.map(trace => ({ ...trace, connected: false })) } } : {}) });
-        await this.stopRecord(record);
+        await this.stopRecord(record, true, true, 'explicit_close');
     }
     async closed(scope) {
         const context = this.workspace.context(scope), path = join(this.directory(), 'context', context.id, 'current.json');
@@ -1050,7 +1079,7 @@ public class ${name} extends GhidraScript {
         for (const record of [...this.running.values()]) {
             try {
                 // Original child handles also permit cleanup of a failed, unready owned stage.
-                await cleanup.stopRecord(record, !record.child);
+                await cleanup.stopRecord(record, !record.child, true, 'owner_dispose');
             }
             catch {
                 failures++;

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

@@ -0,0 +1,9 @@
+import type { LocatedEntry } from './function-entries.js';
+/** Validate evidence and selection policy independently, before any function inspection/save. */
+export declare function locatedBoundaries(raw: unknown, request: {
+    addresses: string[];
+    unwindMaximum: number;
+}, modification: string): {
+    entries: Map<string, LocatedEntry>;
+    boundaryLookup: Record<string, unknown>;
+};

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;
+}>;