@eyeauras/insight-cli 0.3.1 → 0.4.0

package/dist/src/string-anchors.js

@@ -0,0 +1,176 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { scope, number, address } from './research.js';
+import { selectedOptions } from './arguments.js';
+import { fail, object, digest, stable } from './model.js';
+import { parseDomainJson } from './json.js';
+export const anchorAlgorithm = 'raw-string-anchors-v1';
+export const anchorEncodings = ['ascii', 'utf16le'];
+const defaults = { max_bytes: 4194304, max_candidates: 10000, timeout_seconds: 5, limit: 100 };
+const big = (s) => BigInt('0x' + s);
+const hex = (v) => { const s = address(v); if (!/^[a-f0-9]{1,16}$/.test(s))
+    fail('invalid', 'String anchors require default-space unsigned addresses.'); return s; };
+const bytes = (s, e) => Buffer.from(s, e === 'ascii' ? 'ascii' : 'utf16le');
+function wellFormed(s) { for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c >= 0xd800 && c <= 0xdbff) {
+        const next = s.charCodeAt(++i);
+        if (!(next >= 0xdc00 && next <= 0xdfff))
+            return false;
+    }
+    else if (c >= 0xdc00 && c <= 0xdfff)
+        return false;
+} return true; }
+function query(raw) {
+    const q = object(raw), text = q.text;
+    if (typeof text !== 'string' || !text.length || text.length > 256 || !wellFormed(text) || text.includes('\0'))
+        fail('invalid', 'Supply a literal of 1–256 UTF-16 units, without NUL or unpaired surrogates.');
+    if (!Array.isArray(q.encodings) || q.encodings.length < 1 || q.encodings.length > 2)
+        fail('invalid', 'Select ascii, utf16le, or both.');
+    const encodings = anchorEncodings.filter(e => q.encodings.includes(e));
+    if (encodings.length !== q.encodings.length)
+        fail('invalid', 'Encodings must be distinct supported values.');
+    if (encodings.includes('ascii') && /[^\x00-\x7f]/.test(text))
+        fail('invalid', 'Text is not representable in ASCII; select utf16le only.');
+    const cap = number(q.cap, 8192, 16);
+    if (cap % 2 || encodings.some(e => bytes(text, e).length > cap))
+        fail('invalid', '--max-string-bytes must be even and fit every encoded needle.');
+    const start = hex(q.start), end = hex(q.end);
+    if (big(start) > big(end))
+        fail('invalid', 'scan-through must not precede scan-from.');
+    return { text, encodings, start, end, cap };
+}
+function budgets(o, base = defaults) { return { max_bytes: number(o.maxBytes ?? base.max_bytes, 16777216, 32768), max_candidates: number(o.maxCandidates ?? base.max_candidates, 100000, 1), timeout_seconds: number(o.timeoutSeconds ?? base.timeout_seconds, 30, 1), limit: number(o.limit ?? base.limit, 1000, 1) }; }
+function frontier(raw, q) {
+    const f = object(raw), at = hex(f.address);
+    if (big(at) < big(q.start) || big(at) > big(q.end) || !q.encodings.includes(f.encoding))
+        fail('invalid', 'String-anchor frontier is outside the query.');
+    return { address: at, encoding: f.encoding };
+}
+function ordinal(f, q) { return big(f.address) * BigInt(q.encodings.length) + BigInt(q.encodings.indexOf(f.encoding)); }
+export function anchorRequest(o, who) {
+    if (o.cursor !== undefined) {
+        if (['text', 'encodings', 'scanFrom', 'scanThrough', 'maxStringBytes'].some(k => o[k] !== undefined))
+            fail('invalid', 'Cursor excludes text, encodings, range and context-cap selectors.');
+        if (typeof o.cursor !== 'string' || o.cursor.length > 16384 || !/^sa1\.[A-Za-z0-9_-]+$/.test(o.cursor))
+            fail('invalid', 'Malformed string-anchor cursor.');
+        let c;
+        try {
+            const encoded = o.cursor.slice(4), b = Buffer.from(encoded, 'base64url');
+            if (b.toString('base64url') !== encoded)
+                throw Error();
+            c = object(parseDomainJson(b.toString('utf8')));
+        }
+        catch {
+            fail('invalid', 'Malformed string-anchor cursor.');
+        }
+        if (c.version !== 1 || c.algorithm !== anchorAlgorithm || stable(c.scope) !== stable(who) || typeof c.view !== 'string' || !/^[a-f0-9]{64}$/.test(c.view))
+            fail('invalid', 'Cursor scope, algorithm or view is incompatible.');
+        const q = query(c.query), b = object(c.budgets);
+        if (['max_bytes', 'max_candidates', 'timeout_seconds', 'limit'].some(k => !Number.isSafeInteger(b[k])))
+            fail('invalid', 'Malformed cursor budgets.');
+        return { query: q, from: frontier(c.next, q), expectedView: c.view, budgets: budgets(o, budgets({ maxBytes: b.max_bytes, maxCandidates: b.max_candidates, timeoutSeconds: b.timeout_seconds, limit: b.limit })) };
+    }
+    if (typeof o.text !== 'string' || typeof o.encodings !== 'string' || typeof o.scanFrom !== 'string' || typeof o.scanThrough !== 'string')
+        fail('invalid', 'Supply --text, --encodings, --scan-from and --scan-through, or --cursor.');
+    const q = query({ text: o.text, encodings: o.encodings.split(',').map(x => x.trim()), start: o.scanFrom, end: o.scanThrough, cap: o.maxStringBytes ?? 1024 });
+    return { query: q, from: { address: q.start, encoding: q.encodings[0] }, budgets: budgets(o) };
+}
+function decoded(raw, e) {
+    if (e === 'ascii')
+        return raw.some(x => x > 127) ? null : raw.toString('ascii');
+    try {
+        return new TextDecoder('utf-16le', { fatal: true, ignoreBOM: true }).decode(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function anchorResult(raw, r, modification) {
+    const v = object(raw), s = object(v.scan), q = r.query, b = r.budgets;
+    if (v.algorithm !== anchorAlgorithm || stable(v.encodings) !== stable(q.encodings) || v.modification !== modification) {
+        if (typeof v.modification === 'string' && v.modification !== modification)
+            fail('binding', 'Native view changed during string-anchor scan.', { reason: 'changed_view' });
+        fail('partial', 'Malformed string-anchor protocol facts.');
+    }
+    if (!Array.isArray(v.matches) || v.matches.length > b.limit || stable(s.from) !== stable(r.from) || s.through !== q.end || typeof s.complete !== 'boolean' || s.complete !== (s.reason === 'exhausted') || !['exhausted', 'byte_limit', 'candidate_limit', 'timeout', 'result_limit'].includes(String(s.reason)))
+        fail('partial', 'Malformed string-anchor coverage.');
+    for (const k of ['bytesRead', 'testedPairs', 'candidates'])
+        if (!Number.isSafeInteger(s[k]) || Number(s[k]) < 0)
+            fail('partial', 'Malformed string-anchor counters.');
+    if (Number(s.bytesRead) > b.max_bytes || Number(s.testedPairs) > Number(s.bytesRead) * q.encodings.length || Number(s.candidates) > b.max_candidates || Number(s.candidates) < v.matches.length || Number(s.candidates) > Number(s.testedPairs) + 1 || !Number.isFinite(s.elapsedMs) || Number(s.elapsedMs) < 0)
+        fail('partial', 'Inconsistent string-anchor budgets.');
+    const next = s.complete ? null : frontier(s.next, q);
+    if (s.complete && s.next !== null || next && ordinal(next, q) < ordinal(r.from, q) || next && BigInt(Number(s.testedPairs)) > ordinal(next, q) - ordinal(r.from, q))
+        fail('partial', 'String-anchor frontier changed.');
+    if (next && ordinal(next, q) === ordinal(r.from, q) && s.reason !== 'timeout')
+        fail('partial', 'String-anchor scan made no progress despite its minimum work budget.');
+    let previous = ordinal(r.from, q) - 1n;
+    for (const item of v.matches) {
+        const row = object(item), at = hex(row.matchAddress), encoding = row.encoding;
+        if (!q.encodings.includes(encoding))
+            fail('partial', 'Unknown string-anchor encoding.');
+        const pair = { address: at, encoding }, order = ordinal(pair, q), needle = bytes(q.text, encoding), unit = encoding === 'ascii' ? 1 : 2, l = object(row.literalCandidate);
+        if (order <= previous || order < ordinal(r.from, q) || next && order >= ordinal(next, q) || big(at) + BigInt(needle.length - 1) > big(q.end) || row.matchByteLength !== needle.length)
+            fail('partial', 'String-anchor pair/order changed.');
+        previous = order;
+        if (typeof l.textBytes !== 'string' || !/^(?:[a-f0-9]{2})+$/.test(l.textBytes) || l.textBytes.length > q.cap * 2)
+            fail('partial', 'String-anchor context bytes are missing or unbounded.');
+        const data = Buffer.from(l.textBytes, 'hex'), from = hex(l.textFrom), offset = big(at) - big(from), left = l.start === null ? null : hex(l.start), right = l.terminatorAddress === null ? null : hex(l.terminatorAddress);
+        if (offset < 0n || offset > BigInt(q.cap) || Number(offset) % unit || data.length % unit || l.textByteLength !== data.length || big(from) < big(q.start) || big(from) + BigInt(data.length - 1) > big(q.end) || !data.subarray(Number(offset), Number(offset) + needle.length).equals(needle))
+            fail('partial', 'String-anchor preview does not contain its byte match.');
+        for (let i = 0; i < data.length; i += unit)
+            if (data[i] === 0 && (unit === 1 || data[i + 1] === 0))
+                fail('partial', 'String-anchor preview crossed a NUL boundary.');
+        const boundaries = ['nul', 'range_edge', 'memory_edge', 'string_limit'];
+        if (!boundaries.includes(String(l.leftBoundary)) || !boundaries.includes(String(l.rightBoundary)) || (l.leftBoundary === 'nul') !== (left !== null) || (l.rightBoundary === 'nul') !== (right !== null))
+            fail('partial', 'String-anchor boundary facts changed.');
+        if (left !== null && (big(left) > big(at) || big(left) < big(q.start) + BigInt(unit) || big(left) > big(from) || row.matchOffsetBytes !== Number(big(at) - big(left)) || Number(big(at) - big(left)) % unit || Number(big(at) - big(left)) > q.cap - needle.length) || left === null && row.matchOffsetBytes !== null)
+            fail('partial', 'Invalid candidate start/offset.');
+        if (right !== null && (big(right) < big(at) + BigInt(needle.length) || big(right) + BigInt(unit - 1) > big(q.end) || big(right) < big(from) + BigInt(data.length) || Number(big(right) - big(at) - BigInt(needle.length)) % unit || Number(big(right) - big(at) - BigInt(needle.length)) > q.cap - needle.length))
+            fail('partial', 'Invalid candidate terminator.');
+        const bounded = left !== null && right !== null, total = bounded ? Number(big(right) - big(left)) : null, text = decoded(data, encoding), complete = bounded && total <= q.cap && text !== null;
+        const reason = complete ? 'complete' : total !== null && total > q.cap || l.leftBoundary === 'string_limit' || l.rightBoundary === 'string_limit' ? 'string_limit' : !bounded ? 'missing_boundary' : 'invalid_encoding';
+        if (l.boundariesComplete !== bounded || l.byteLength !== total || l.text !== text || l.decoding !== (text === null ? 'invalid' : 'valid') || l.complete !== complete || l.reason !== reason || complete && (from !== left || data.length !== total))
+            fail('partial', 'Inconsistent string-anchor context/decoding facts.');
+    }
+    if (Buffer.byteLength(JSON.stringify(v)) > 1000000)
+        fail('limit', 'String-anchor native response exceeds its envelope reserve.');
+    return v;
+}
+export async function inspectAnchors(backend, who, r, view, observation, observe) {
+    if (r.expectedView !== undefined && r.expectedView !== view)
+        fail('binding', 'String-anchor continuation view changed.', { reason: 'changed_view' });
+    const modification = object(observation).modification;
+    if (typeof modification !== 'string')
+        fail('unsupported', 'String anchors require guarded native observations.');
+    const q = r.query;
+    let raw;
+    try {
+        raw = await backend.call(who, '/insight/string-anchors/v1', { text: q.text, encodings: q.encodings.join(','), scan_from: q.start, scan_through: q.end, resume_address: r.from.address, resume_encoding: r.from.encoding, max_string_bytes: q.cap, ...r.budgets });
+    }
+    catch (error) {
+        if (digest(observation) !== digest(await observe()))
+            fail('binding', 'Native view changed during string-anchor scan.', { reason: 'changed_view' });
+        throw error;
+    }
+    if (digest(observation) !== digest(await observe()))
+        fail('binding', 'Native view changed during string-anchor scan.', { reason: 'changed_view' });
+    const value = anchorResult(raw, r, modification), cursor = value.scan && object(value.scan).complete ? null : 'sa1.' + Buffer.from(stable({ version: 1, algorithm: anchorAlgorithm, scope: who, query: q, next: object(value.scan).next, view, budgets: r.budgets })).toString('base64url');
+    const result = { ...who, value: { ...value, view: { identity: view }, cursor } };
+    if (Buffer.byteLength(JSON.stringify(result)) > 1048576)
+        fail('limit', 'String-anchor response exceeds one MiB.');
+    return result;
+}
+export function stringAnchorCommands(research) {
+    return [command('strings', 'String research', [command('anchors', 'Find raw literal byte hits and separate bounded NUL-delimited candidate context', ({ options: o }, c) => { const who = scope(o); return research(c).stringAnchors(who, anchorRequest(o, who)); }, { permission: Permission.ReadOnly, options: [...selectedOptions,
+                    { flags: '--text <literal>', description: 'Case-sensitive literal, 1–256 UTF-16 units, no NUL' },
+                    { flags: '--encodings <encodings>', description: 'Explicit ascii, utf16le, or both; no alignment assumption' },
+                    { flags: '--scan-from <address>', description: 'Inclusive range start; context stays inside the range' },
+                    { flags: '--scan-through <address>', description: 'Inclusive range end; the whole needle must fit' },
+                    { flags: '--max-string-bytes <count>', description: 'Even candidate/preview payload cap 16–8192, default 1024' },
+                    { flags: '--cursor <token>', description: 'Stateless continuation; excludes text/encodings/range/context selectors' },
+                    { flags: '--max-bytes <count>', description: '32768–16777216 actual bytes read including context/rereads; default 4194304' },
+                    { flags: '--max-candidates <count>', description: '1–100000 raw matched address/encoding pairs; default 10000' },
+                    { flags: '--timeout-seconds <count>', description: '1–30 second cooperative scan deadline; default 5' },
+                    { flags: '--limit <count>', description: '1–1000 raw hits per call; default 100' }] })])];
+}

package/dist/src/sync-policy.js

@@ -40,6 +40,9 @@ export class Synchronization {
     async execute(selected, path, input, run) {
         const configured = this.workspace.context(selected).syncPolicy ?? manualPolicy;
         const caller = input.requestId === undefined ? undefined : id(input.requestId);
+        const recorded = caller ? this.workspace.scopedRequest(selected, caller) : undefined;
+        if (caller && recorded?.id === caller)
+            return run(caller);
         const previous = caller ? this.workspace.administrationByCaller(caller) : undefined;
         if (!previous && (configured.publish === 'manual' && configured.refresh === 'manual' || input.requestId !== undefined && this.workspace.requestByCaller(id(input.requestId))))
             return run(input.requestId === undefined ? '' : id(input.requestId));

package/dist/src/timed-backend.d.ts

@@ -0,0 +1,3 @@
+import type { ResearchBackend } from './research.js';
+/** Observe existing boundaries; retain original method receivers and domain behavior. */
+export declare function timedBackend(backend: ResearchBackend): ResearchBackend;

package/dist/src/timed-backend.js

@@ -0,0 +1,16 @@
+import { timed } from './internal-timing.js';
+/** Observe existing boundaries; retain original method receivers and domain behavior. */
+export function timedBackend(backend) {
+    return new Proxy(backend, { get(target, key) {
+            const member = Reflect.get(target, key);
+            if (typeof member !== 'function')
+                return member;
+            if (key === 'open')
+                return (...args) => timed('context.open', 'open', async () => Reflect.apply(member, target, args));
+            if (key === 'saved')
+                return (...args) => timed('context.save', 'saved', async () => Reflect.apply(member, target, args));
+            if (key === 'call')
+                return (...args) => timed('backend.operation', String(args[1]), async () => Reflect.apply(member, target, args));
+            return member.bind(target);
+        } });
+}

package/dist/src/transport.d.ts

@@ -17,6 +17,7 @@ export declare class HttpBridge {
     private schema?;
     constructor(endpoint: string, fetch?: typeof globalThis.fetch, signal?: AbortSignal | undefined, token?: string | undefined, timeoutMilliseconds?: number | undefined, saveTimeoutMilliseconds?: number);
     private request;
+    private requestBody;
     instance(): Promise<Record<string, unknown>>;
     descriptor(path: string): Promise<Descriptor>;
     call(path: string, params?: Record<string, unknown>): Promise<unknown>;

package/dist/src/transport.js

@@ -1,5 +1,6 @@
 import { fail, object } from './model.js';
 import { parseDomainJson } from './json.js';
+import { timed } from './internal-timing.js';
 import { CliError } from '@eyeauras/cli-factory';
 /** The pinned GhidraMCP HTTP side of a dedicated bridge. No discovery by project name. */
 export class HttpBridge {
@@ -26,6 +27,9 @@ export class HttpBridge {
             fail('invalid', 'Bridge timeout is outside the supported bound.');
     }
     async request(path, method, query, body) {
+        return timed('native.http', path, () => this.requestBody(path, method, query, body));
+    }
+    async requestBody(path, method, query, body) {
         const url = new URL(path, this.endpoint);
         // Import includes synchronous auto-analysis. Keep discovery/ordinary requests short,
         // while allowing a real executable to finish its first analysis without losing the reply.

package/dist/src/workspace.js

@@ -197,9 +197,12 @@ export class Workspace {
     existingRequest(callerId, intentHash) {
         if (callerId === undefined)
             return;
-        if (this.db.prepare('SELECT id FROM administration_requests WHERE caller_id=?').get(id(callerId)))
+        // A previous build may have reserved a blocked retry under this generated ID.
+        // The recorded identity still selects its original intent, not that newer caller ID.
+        const recorded = this.db.prepare('SELECT id,hash FROM requests WHERE id=?').get(id(callerId));
+        if (!recorded && this.db.prepare('SELECT id FROM administration_requests WHERE caller_id=?').get(id(callerId)))
             fail('idempotency', 'Request ID already identifies a profile administration operation.');
-        const row = this.db.prepare('SELECT id,hash FROM requests WHERE caller_id=?').get(id(callerId));
+        const row = recorded ?? this.db.prepare('SELECT id,hash FROM requests WHERE caller_id=?').get(id(callerId));
         if (!row)
             return;
         if (row.hash !== intentHash)

package/package.json

@@ -1,10 +1,21 @@
 {
   "name": "@eyeauras/insight-cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "Agent-facing durable sessions and isolated Ghidra research contexts",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./persistent": {
+      "types": "./dist/src/persistent-client.d.ts",
+      "default": "./dist/src/persistent-client.js"
+    },
+    "./*": "./*"
+  },
   "bin": {
     "insight-cli": "./dist/src/bin.js"
   },

package/references/native/InsightAnchorScan.java

@@ -0,0 +1,135 @@
+package com.eyeauras.insight;
+
+import java.math.BigInteger;
+import java.nio.ByteBuffer;
+import java.nio.charset.*;
+import java.util.*;
+import java.util.function.LongSupplier;
+
+/** Pure bounded raw-memory algorithm. No Ghidra, filesystem, process or persistent query state. */
+public final class InsightAnchorScan {
+  public static final String ALGORITHM="raw-string-anchors-v1";
+  public interface Bytes { int read(BigInteger at,byte[] destination)throws Exception; }
+  public record Span(BigInteger start,BigInteger end) {}
+  public record Config(String text,List<String> encodings,BigInteger start,BigInteger end,
+      BigInteger resume,String resumeEncoding,int cap,int maxBytes,int maxCandidates,int seconds,int limit) {
+    public Config {
+      if(text==null||text.isEmpty()||text.length()>256||text.indexOf(0)>=0)throw new IllegalArgumentException("Expected 1–256 UTF-16 units without NUL");
+      for(int i=0;i<text.length();i++)if(Character.isSurrogate(text.charAt(i))){
+        if(!Character.isHighSurrogate(text.charAt(i))||i+1>=text.length()||!Character.isLowSurrogate(text.charAt(++i)))throw new IllegalArgumentException("Unpaired surrogate");
+      }
+      if(!List.of(List.of("ascii"),List.of("utf16le"),List.of("ascii","utf16le")).contains(encodings))throw new IllegalArgumentException("Expected canonical ascii,utf16le encodings");
+      if(encodings.contains("ascii")&&text.chars().anyMatch(c->c>127))throw new IllegalArgumentException("Text is not representable in ASCII");
+      if(start.signum()<0||end.bitLength()>64||start.compareTo(end)>0||resume.compareTo(start)<0||resume.compareTo(end)>0||!encodings.contains(resumeEncoding))throw new IllegalArgumentException("Invalid range/frontier");
+      if(cap<16||cap>8192||(cap&1)!=0||encodings.stream().anyMatch(e->encoded(text,e).length>cap))throw new IllegalArgumentException("Invalid candidate byte cap");
+      if(maxBytes<32768||maxBytes>16777216||maxCandidates<1||maxCandidates>100000||seconds<1||seconds>30||limit<1||limit>1000)throw new IllegalArgumentException("Invalid page budgets");
+      encodings=List.copyOf(encodings);
+    }
+  }
+  public static byte[] encoded(String text,String encoding){return text.getBytes(encoding.equals("ascii")?StandardCharsets.US_ASCII:StandardCharsets.UTF_16LE);}
+  private static final BigInteger ONE=BigInteger.ONE,PAGE=BigInteger.valueOf(4096);
+  private static String hex(BigInteger at){return at.toString(16);}
+  private static Map<String,Object> frontier(BigInteger at,String encoding){return Map.of("address",hex(at),"encoding",encoding);}
+  private static final class Pause extends RuntimeException {final String reason;Pause(String reason){this.reason=reason;}}
+  private record Page(BigInteger start,BigInteger end,byte[] bytes) {}
+  private record Probe(int bytes,String boundary,BigInteger nul) {}
+  private final Config c;private final List<Span> spans;private final Bytes source;private final LongSupplier clock;
+  private final long started;private final byte[][] needles;private final LinkedHashMap<BigInteger,Page> cache=new LinkedHashMap<>(16,.75f,true);
+  private Page last,positionPage;private int positionIndex,encodingIndex,bytesRead,testedPairs,candidates,estimatedResultBytes=2048;
+  private BigInteger position;private final List<Object> matches=new ArrayList<>();
+  public InsightAnchorScan(Config config,List<Span> spans,Bytes source,LongSupplier clock){
+    c=config;this.spans=List.copyOf(spans);this.source=source;this.clock=clock;started=clock.getAsLong();
+    needles=c.encodings.stream().map(e->encoded(c.text,e)).toArray(byte[][]::new);position=c.resume;encodingIndex=c.encodings.indexOf(c.resumeEncoding);
+    BigInteger previous=null;
+    for(Span s:spans){if(s.start.compareTo(c.start)<0||s.end.compareTo(c.end)>0||s.start.compareTo(s.end)>0||previous!=null&&s.start.compareTo(previous.add(ONE))<=0)throw new IllegalArgumentException("Expected clipped, sorted, merged spans");previous=s.end;}
+  }
+  private void deadline(){if(clock.getAsLong()-started>=c.seconds*1000000000L)throw new Pause("timeout");}
+  private BigInteger at(){return positionPage==null?position:positionPage.start.add(BigInteger.valueOf(positionIndex));}
+  private Page page(BigInteger at,Span span)throws Exception{
+    if(last!=null&&at.compareTo(last.start)>=0&&at.compareTo(last.end)<=0)return last;
+    BigInteger base=at.divide(PAGE).multiply(PAGE),start=base.max(span.start),end=base.add(PAGE).subtract(ONE).min(span.end);
+    Page hit=cache.get(start);if(hit!=null)return last=hit;
+    deadline();int length=end.subtract(start).intValueExact()+1;
+    if(length>c.maxBytes-bytesRead)throw new Pause("byte_limit");
+    byte[] data=new byte[length];int read=source.read(start,data);if(read!=length)throw new IllegalStateException("Incomplete initialized-memory read");
+    bytesRead+=read;Page value=new Page(start,end,data);cache.put(start,value);if(cache.size()>8)cache.remove(cache.keySet().iterator().next());return last=value;
+  }
+  private int byteAt(BigInteger at,Span span)throws Exception{Page p=page(at,span);return p.bytes[at.subtract(p.start).intValueExact()]&255;}
+  private byte[] copy(BigInteger at,int count,Span span)throws Exception{
+    byte[] data=new byte[count];int offset=0;
+    while(offset<count){Page p=page(at,span);int index=at.subtract(p.start).intValueExact(),n=Math.min(count-offset,p.bytes.length-index);System.arraycopy(p.bytes,index,data,offset,n);offset+=n;at=at.add(BigInteger.valueOf(n));}
+    return data;
+  }
+  private int unit(BigInteger at,int width,Span span)throws Exception{return width==1?byteAt(at,span):byteAt(at,span)|(byteAt(at.add(ONE),span)<<8);}
+  private Probe probe(BigInteger match,int length,int width,Span span,boolean left)throws Exception{
+    int count=0,allowance=c.cap-length;BigInteger cursor=left?match.subtract(BigInteger.valueOf(width)):match.add(BigInteger.valueOf(length));
+    while(true){
+      if((count&127)==0)deadline();
+      if(cursor.compareTo(span.start)<0||cursor.add(BigInteger.valueOf(width-1)).compareTo(span.end)>0){
+        boolean range=left?cursor.compareTo(c.start)<0:cursor.add(BigInteger.valueOf(width-1)).compareTo(c.end)>0;
+        return new Probe(count,range?"range_edge":"memory_edge",null);
+      }
+      // At the payload cap the next code unit may still be the NUL (not payload).
+      if(unit(cursor,width,span)==0)return new Probe(count,"nul",cursor);
+      if(count==allowance)return new Probe(count,"string_limit",null);
+      count+=width;cursor=left?cursor.subtract(BigInteger.valueOf(width)):cursor.add(BigInteger.valueOf(width));
+    }
+  }
+  private Map<String,Object> candidate(BigInteger match,int index,Span span)throws Exception{
+    String encoding=c.encodings.get(index);int width=encoding.equals("ascii")?1:2,length=needles[index].length;
+    Probe left=probe(match,length,width,span,true),right=probe(match,length,width,span,false);
+    int spare=c.cap-length,l=Math.min(left.bytes,(spare/2/width)*width),r=Math.min(right.bytes,spare-l);
+    l+=Math.min(left.bytes-l,spare-l-r);r+=Math.min(right.bytes-r,spare-l-r);
+    BigInteger textFrom=match.subtract(BigInteger.valueOf(l));byte[] data=copy(textFrom,l+length+r,span);String text=null;
+    try{text=(encoding.equals("ascii")?StandardCharsets.US_ASCII:StandardCharsets.UTF_16LE).newDecoder().onMalformedInput(CodingErrorAction.REPORT).onUnmappableCharacter(CodingErrorAction.REPORT).decode(ByteBuffer.wrap(data)).toString();}catch(CharacterCodingException ignored){}
+    boolean bounded=left.nul!=null&&right.nul!=null;int total=left.bytes+length+right.bytes;
+    boolean complete=bounded&&total<=c.cap&&text!=null;
+    String reason=complete?"complete":bounded&&total>c.cap||left.boundary.equals("string_limit")||right.boundary.equals("string_limit")?"string_limit":!bounded?"missing_boundary":"invalid_encoding";
+    Map<String,Object> literal=new LinkedHashMap<>();literal.put("start",left.nul==null?null:hex(left.nul.add(BigInteger.valueOf(width))));literal.put("terminatorAddress",right.nul==null?null:hex(right.nul));
+    literal.put("byteLength",bounded?total:null);literal.put("textFrom",hex(textFrom));literal.put("text",text);literal.put("textBytes",HexFormat.of().formatHex(data));literal.put("textByteLength",data.length);
+    literal.put("leftBoundary",left.boundary);literal.put("rightBoundary",right.boundary);literal.put("boundariesComplete",bounded);literal.put("decoding",text==null?"invalid":"valid");literal.put("complete",complete);literal.put("reason",reason);
+    Map<String,Object> row=new LinkedHashMap<>();row.put("encoding",encoding);row.put("matchAddress",hex(match));row.put("matchByteLength",length);row.put("matchOffsetBytes",left.nul==null?null:left.bytes);row.put("literalCandidate",literal);return row;
+  }
+  private boolean match(Page p,int index,int which,Span span)throws Exception{
+    byte[] needle=needles[which];if(p.bytes[index]!=needle[0])return false;
+    BigInteger at=p.start.add(BigInteger.valueOf(index));if(at.add(BigInteger.valueOf(needle.length-1)).compareTo(span.end)>0)return false;
+    if(index+needle.length<=p.bytes.length){for(int i=1;i<needle.length;i++)if(p.bytes[index+i]!=needle[i])return false;return true;}
+    for(int i=1;i<needle.length;i++){if((i&63)==0)deadline();if(byteAt(at.add(BigInteger.valueOf(i)),span)!=(needle[i]&255))return false;}return true;
+  }
+  public Map<String,Object> run()throws Exception{
+    String reason="exhausted";boolean complete=true;
+    try{
+      for(Span span:spans){
+        if(span.end.compareTo(c.resume)<0)continue;
+        BigInteger current=span.start.max(c.resume);int first=current.equals(c.resume)?c.encodings.indexOf(c.resumeEncoding):0;
+        while(current.compareTo(span.end)<=0){
+          position=current;positionPage=null;encodingIndex=first;
+          // Limits apply only while there remains an eligible unchecked pair.
+          if(matches.size()>=c.limit||estimatedResultBytes>=900000)throw new Pause("result_limit");
+          if(candidates>=c.maxCandidates)throw new Pause("candidate_limit");
+          Page p=page(current,span);positionPage=p;
+          for(int i=current.subtract(p.start).intValueExact();i<p.bytes.length;i++){
+            positionIndex=i;
+            for(int e=first;e<needles.length;e++){
+              encodingIndex=e;if((testedPairs&1023)==0)deadline();
+              if(matches.size()>=c.limit||estimatedResultBytes>=900000)throw new Pause("result_limit");
+              if(candidates>=c.maxCandidates)throw new Pause("candidate_limit");
+              if(match(p,i,e,span)){
+                candidates++;Map<String,Object> row=candidate(at(),e,span);
+                Map<?,?> literal=(Map<?,?>)row.get("literalCandidate");int cost=2048+8*((String)literal.get("textBytes")).length();
+                if(estimatedResultBytes+cost>900000)throw new Pause("result_limit");
+                matches.add(row);estimatedResultBytes+=cost;
+              }
+              testedPairs++;
+            }
+            first=0;
+          }
+          current=p.end.add(ONE);first=0;
+        }
+      }
+    }catch(Pause pause){complete=false;reason=pause.reason;}
+    Map<String,Object> scan=new LinkedHashMap<>();scan.put("from",frontier(c.resume,c.resumeEncoding));scan.put("through",hex(c.end));scan.put("next",complete?null:frontier(at(),c.encodings.get(encodingIndex)));
+    scan.put("complete",complete);scan.put("reason",reason);scan.put("bytesRead",bytesRead);scan.put("testedPairs",testedPairs);scan.put("candidates",candidates);scan.put("elapsedMs",Math.max(0,(clock.getAsLong()-started)/1000000.0));
+    return Map.of("algorithm",ALGORITHM,"encodings",c.encodings,"matches",matches,"scan",scan);
+  }
+}

package/references/native/InsightCodeReferences.java

@@ -0,0 +1,129 @@
+import ghidra.app.script.GhidraScript;
+import ghidra.app.util.PseudoDisassembler;
+import ghidra.app.util.PseudoInstruction;
+import ghidra.program.model.address.*;
+import ghidra.program.model.mem.MemoryBlock;
+import com.google.gson.*;
+import java.nio.charset.StandardCharsets;
+import java.util.*;
+
+/** Bounded candidate discovery only. Never creates instructions, functions or references. */
+public class InsightCodeReferences extends GhidraScript {
+  static final String ALGORITHM="x86-64-code-reference-candidates-v1";
+  static final List<String> FORMS=List.of("call-rel32","lea-rip","mov-rip","call-rip-slot");
+  JsonObject p; long deadline,started; int bytesRead,tested,visited,maxBytes,maxCandidates,limit;
+  String reason="exhausted"; Address next; Set<Address> targets=new HashSet<>(); List<String> forms=new ArrayList<>();
+  List<Object> matches=new ArrayList<>();
+  Map<String,Object> map(Object... pairs){Map<String,Object> m=new LinkedHashMap<>();for(int i=0;i<pairs.length;i+=2)m.put((String)pairs[i],pairs[i+1]);return m;}
+  int number(String k,int d,int min,int max){int v=p.has(k)?p.get(k).getAsInt():d;if(v<min||v>max)throw new IllegalArgumentException(k+" outside supported bounds");return v;}
+  Address address(String s){if(!s.matches("[a-fA-F0-9]{1,16}"))throw new IllegalArgumentException("Default-space 64-bit hexadecimal address required");return currentProgram.getAddressFactory().getDefaultAddressSpace().getAddress(Long.parseUnsignedLong(s,16));}
+  String hex(Address a){return Long.toUnsignedString(a.getOffset(),16);}
+  boolean expired()throws Exception{monitor.checkCancelled();return System.nanoTime()>=deadline;}
+  record Encoding(String form,int length,int operand,int bits,int delta,String role){}
+  Encoding encoding(byte[] b,int start){
+    int i=start,rex=0;boolean word=false;
+    while(i<b.length&&i-start<15){int v=b[i]&255;if(v==0x66||v==0x26||v==0x2e||v==0x36||v==0x3e){word|=v==0x66;rex=0;i++;}else if(v>=0x40&&v<=0x4f){rex=v;i++;}else break;}
+    if(i>=b.length)return null;int op=b[i]&255,length,disp,operand,bits;String form,role;
+    if(op==0xe8){form="call-rel32";role="direct-call-target";length=i-start+5;disp=i+1;operand=0;bits=64;}
+    else{
+      if(i+1>=b.length)return null;int m=b[i+1]&255;if((m&0xc7)!=5)return null;
+      if(op==0x8d){form="lea-rip";operand=1;}
+      else if(op==0x88||op==0x89||op==0x8a||op==0x8b){form="mov-rip";operand=op==0x88||op==0x89?0:1;}
+      else if(op==0xff&&((m>>3)&7)==2){form="call-rip-slot";operand=0;}
+      else return null;
+      role=form.equals("call-rip-slot")?"pointer-slot":"effective-address";
+      length=i-start+6;disp=i+2;bits=form.equals("call-rip-slot")?64:op==0x88||op==0x8a?8:(rex&8)!=0?64:word?16:32;
+    }
+    if(length>15||start+length>b.length)return null;
+    int delta=(b[disp]&255)|((b[disp+1]&255)<<8)|((b[disp+2]&255)<<16)|(b[disp+3]<<24);
+    return new Encoding(form,length,operand,bits,delta,role);
+  }
+  boolean compatible(PseudoInstruction i,Encoding e,Address target){
+    if(i==null||i.getLength()!=e.length)return false;
+    if(e.form.equals("call-rel32"))return i.getMnemonicString().equalsIgnoreCase("CALL")&&i.getFlowType().isCall()&&!i.getFlowType().isComputed()&&Arrays.asList(i.getFlows()).contains(target);
+    if(e.form.equals("call-rip-slot"))return i.getMnemonicString().equalsIgnoreCase("CALL")&&i.getFlowType().isCall()&&i.getFlowType().isComputed();
+    if(!i.getMnemonicString().equalsIgnoreCase(e.form.equals("lea-rip")?"LEA":"MOV"))return false;
+    var register=i.getRegister(e.operand==0?1:0);return register!=null&&register.getBitLength()==e.bits;
+  }
+  String boundary(Address at,PseudoInstruction decoded,byte[] bytes)throws Exception{
+    var listing=currentProgram.getListing();var stored=listing.getInstructionContaining(at);
+    if(stored==null){var after=listing.getInstructionAfter(at);return after!=null&&after.getAddress().compareTo(at.addNoWrap(bytes.length-1))<=0?"listing-conflict":"unconfirmed";}
+    if(!stored.getAddress().equals(at)||stored.getLength()!=decoded.getLength()||!Arrays.equals(stored.getBytes(),bytes)||!stored.getMnemonicString().equals(decoded.getMnemonicString())||stored.getNumOperands()!=decoded.getNumOperands())return "listing-conflict";
+    for(int i=0;i<stored.getNumOperands();i++)if(!stored.getDefaultOperandRepresentation(i).equals(decoded.getDefaultOperandRepresentation(i)))return "listing-conflict";
+    return "listing-confirmed";
+  }
+  Object scan()throws Exception{
+    if(!currentProgram.getLanguageID().toString().startsWith("x86:LE:64:")||currentProgram.getAddressFactory().getDefaultAddressSpace().getSize()!=64)throw new UnsupportedOperationException("Code references V1 requires x86-64 little-endian default memory space");
+    var mode=currentProgram.getRegister("longMode");if(mode==null)throw new UnsupportedOperationException("64-bit decode mode is unavailable");
+    Address from=address(p.get("scan_from").getAsString()),through=address(p.get("scan_through").getAsString());if(from.compareTo(through)>0)throw new IllegalArgumentException("Inverted scan range");
+    var ts=p.getAsJsonArray("targets");if(ts.size()<1||ts.size()>64)throw new IllegalArgumentException("Select 1..64 targets");for(var t:ts)if(!targets.add(address(t.getAsString())))throw new IllegalArgumentException("Duplicate target");
+    var fs=p.getAsJsonArray("forms");for(String f:FORMS)for(var v:fs)if(f.equals(v.getAsString()))forms.add(f);if(forms.isEmpty()||new HashSet<>(forms).size()!=fs.size()||forms.size()!=fs.size())throw new IllegalArgumentException("Unsupported or duplicate form");
+    maxBytes=number("max_bytes",4194304,15,16777216);maxCandidates=number("max_candidates",200000,1,1000000);limit=number("limit",100,1,1000);
+    started=System.nanoTime();deadline=started+number("timeout_seconds",5,1,30)*1000000000L;
+    List<Address[]> runs=new ArrayList<>();var blocks=currentProgram.getMemory().getBlocks();Arrays.sort(blocks,Comparator.comparing(MemoryBlock::getStart));
+    for(var block:blocks){
+      if(expired()){reason="timeout";next=from;return result(from,through);}
+      if(!block.isInitialized()||!block.isExecute()||!block.getStart().getAddressSpace().equals(from.getAddressSpace())||block.getEnd().compareTo(from)<0||block.getStart().compareTo(through)>0)continue;
+      Address a=block.getStart().compareTo(from)<0?from:block.getStart(),z=block.getEnd().compareTo(through)>0?through:block.getEnd();
+      if(!runs.isEmpty()&&a.equals(runs.getLast()[1].next()))runs.getLast()[1]=z;
+      else runs.add(new Address[]{a,z});
+    }
+    var decoder=new PseudoDisassembler(currentProgram);
+    outer:for(int runIndex=0;runIndex<runs.size();runIndex++){
+      var run=runs.get(runIndex);Address at=run[0];
+      while(at.compareTo(run[1])<=0){
+        next=at;
+        if(expired()){reason="timeout";break outer;}
+        int remaining=maxBytes-bytesRead;long available=run[1].subtract(at)+1;
+        if(remaining<Math.min(15,available)){reason="byte_limit";break outer;}
+        int count=(int)Math.min(Math.min(65550,available),remaining);byte[] data=new byte[count];
+        if(currentProgram.getMemory().getBytes(at,data)!=count)throw new IllegalStateException("Incomplete initialized executable memory read");bytesRead+=count;
+        int positions=count==available?count:count-14;
+        for(int i=0;i<positions;i++){
+          Address here=at.addNoWrap(i);next=here;
+          if(expired()){reason="timeout";break outer;}
+          Encoding e=encoding(data,i);
+          if(e!=null&&forms.contains(e.form)){
+            if(visited==maxCandidates){reason="candidate_limit";break outer;}
+            var modeValue=currentProgram.getProgramContext().getValue(mode,here,false);
+            if(modeValue==null||!modeValue.equals(java.math.BigInteger.ONE))throw new UnsupportedOperationException("Candidate encountered outside known 64-bit decode mode");
+            visited++;
+            Address target=here.addWrap(e.length+(long)e.delta);
+            if(targets.contains(target)){
+              PseudoInstruction instruction=null;
+              try{instruction=decoder.disassemble(here,Arrays.copyOfRange(data,i,Math.min(data.length,i+15)));}
+              catch(ghidra.program.model.lang.InsufficientBytesException|ghidra.program.model.lang.UnknownInstructionException ignored){}
+              catch(ghidra.program.model.lang.UnknownContextException error){throw new UnsupportedOperationException("Native decoder context unavailable");}
+              if(compatible(instruction,e,target)){
+                byte[] bytes=Arrays.copyOfRange(data,i,i+e.length);String display=instruction.toString();
+                matches.add(map("from",hex(here),"to",hex(target),"form",e.form,"bytes",HexFormat.of().formatHex(bytes),"length",e.length,"operand_index",e.operand,"operand_bits",e.bits,"target_role",e.role,"validation","decoded","boundary",boundary(here,instruction,bytes),"instruction",display.substring(0,Math.min(512,display.length()))));
+              }
+            }
+          }
+          tested++;
+          if(here.equals(through)||here.equals(run[1])&&runIndex==runs.size()-1)next=null;
+          else next=here.addNoWrap(1);
+          if(matches.size()==limit&&next!=null){reason="result_limit";break outer;}
+        }
+        if(positions==available)break;
+        at=at.addNoWrap(positions);
+      }
+    }
+    if(reason.equals("exhausted"))next=null;
+    return result(from,through);
+  }
+  Object result(Address from,Address through){return map("algorithm",ALGORITHM,"language",currentProgram.getLanguageID().toString(),"forms",forms,"matches",matches,
+    "scan",map("from",hex(from),"through",hex(through),"next_start",next==null?null:hex(next),"complete",reason.equals("exhausted"),"reason",reason,"bytes_read",bytesRead,"tested_starts",tested,"visited_candidates",visited,"elapsed_ms",(System.nanoTime()-started)/1000000.0),
+    "coverage","Every byte start in initialized executable default-space memory, in address order; adjacent eligible blocks merge. Instructions fit entirely within the requested range. Overlapping decodes are separate candidates.",
+    "limitations",List.of("Decoded byte candidates do not prove instruction boundaries, execution or callgraph membership.","Indirect CALL targets identify pointer slots; pointees are never followed.","Only explicit V1 encodings; 67, FS/GS, LOCK/REP, SIMD and immediate MOV encodings are excluded at that start. A later start inside their bytes may still be a candidate."));}
+  public void run()throws Exception{
+    Map<String,Object> output;long modification=currentProgram.getModificationNumber();
+    try{
+      var request=JsonParser.parseString(new String(Base64.getDecoder().decode(getScriptArgs()[0]),StandardCharsets.UTF_8)).getAsJsonObject();
+      if(!request.get("operation").getAsString().equals("/code_references"))throw new IllegalArgumentException("Unknown code-reference operation");p=request.getAsJsonObject("parameters");
+      var value=(Map<String,Object>)scan();if(currentProgram.getModificationNumber()!=modification)throw new IllegalStateException("Read-only scan changed program modification counter");
+      value.put("read_only",map("modification_unchanged",true,"modification",Long.toString(modification)));output=map("value",value);
+    }catch(Exception error){output=map("error",map("code",error instanceof UnsupportedOperationException?"unsupported":error instanceof IllegalArgumentException?"invalid":"partial","message",Objects.toString(error.getMessage(),"Native code-reference scan failed")));}
+    println("INSIGHT_QUERY:"+new GsonBuilder().serializeNulls().create().toJson(output));
+  }
+}

package/references/native/InsightFunctionBoundaries.java

@@ -0,0 +1,56 @@
+package com.eyeauras.insight;
+
+import com.xebyte.core.*;
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import ghidra.program.model.listing.Program;
+import java.math.BigInteger;
+import java.util.*;
+
+/** Authenticated bounded runtime-region evidence for explicitly selected open programs. */
+public final class InsightFunctionBoundaries {
+  private static final Gson JSON=new GsonBuilder().disableHtmlEscaping().serializeNulls().create();
+  private final ProgramProvider programs;private final ThreadingStrategy threading;
+  public InsightFunctionBoundaries(ProgramProvider programs,ThreadingStrategy threading){this.programs=programs;this.threading=threading;}
+  @McpTool(path="/insight/function-boundaries/v1",method="GET",description="Compare recorded function membership with current mapped PE32+ AMD64 runtime regions; no semantic reconstruction",access=ToolAccess.READ_ONLY)
+  public Response boundaries(@Param(value="program",source=ParamSource.QUERY,allowEmpty=false) String path,
+      @Param(value="addresses",source=ParamSource.QUERY,allowEmpty=false) String addresses,
+      @Param(value="max_unwind_bytes",source=ParamSource.QUERY,allowEmpty=false) int maximum)throws Exception {
+    if(maximum<1||maximum>16777216||addresses==null||addresses.length()>339)throw new IllegalArgumentException("Expected 1–20 addresses and byte budget 1–16777216");
+    String[] words=addresses.split(",",-1);if(words.length<1||words.length>20)throw new IllegalArgumentException("Expected 1–20 addresses");
+    Set<String> unique=new HashSet<>();for(String word:words)if(!word.matches("0|[1-9a-f][a-f0-9]{0,15}")||!unique.add(word))throw new IllegalArgumentException("Expected distinct canonical addresses");
+    return threading.executeRead(()->{
+      if(programs==null||path==null||!path.startsWith("/")||path.length()>4096)throw new IllegalArgumentException("Explicit open program path required");
+      Program program=null;for(Program p:programs.getAllOpenPrograms())if(p!=null&&!p.isClosed()&&p.getDomainFile()!=null&&path.equals(p.getDomainFile().getPathname())){if(program!=null&&program!=p)throw new IllegalStateException("Ambiguous program path");program=p;}
+      if(program==null)throw new IllegalArgumentException("Program is not open");
+      var space=program.getAddressFactory().getDefaultAddressSpace();var memory=program.getMemory();var functions=program.getFunctionManager();long modification=program.getModificationNumber();
+      long lookupStarted=System.nanoTime();List<InsightPeRanges.Span> spans=new ArrayList<>();
+      for(var block:memory.getBlocks())if(block.isInitialized()&&block.getStart().getAddressSpace().equals(space))spans.add(new InsightPeRanges.Span(new BigInteger(Long.toUnsignedString(block.getStart().getOffset(),16),16),new BigInteger(Long.toUnsignedString(block.getEnd().getOffset(),16),16).add(BigInteger.ONE),block.isExecute()));
+      InsightPeRanges.Result scan;
+      if(space.getSize()!=64||space.getAddressableUnitSize()!=1||!program.getLanguageID().toString().equals("x86:LE:64:default"))scan=new InsightPeRanges.Result(Map.of("state","unavailable","complete",false,"reason","unsupported_language","headersSource","current-mapped-memory","recordCount",0,"recordsValidated",0,"bytesRead",0,"maximumBytes",maximum,"deadlineMilliseconds",5000),List.of());
+      else scan=new InsightPeRanges(new BigInteger(Long.toUnsignedString(program.getImageBase().getOffset(),16),16),spans,(at,out)->memory.getBytes(space.getAddress(at.longValue()),out),maximum,System::nanoTime,Arrays.stream(words).map(w->new BigInteger(w,16)).toList(),lookupStarted).run();
+      Map<String,Object> items=new LinkedHashMap<>();boolean complete=Boolean.TRUE.equals(scan.lookup().get("complete"));
+      for(String word:words){
+        BigInteger query=new BigInteger(word,16);Map<String,Object> row=new LinkedHashMap<>();Map<String,Object> database=null;
+        if(query.bitLength()<=space.getSize()){
+          var at=space.getAddress(query.longValue());var f=functions.getFunctionAt(at);String kind="exact-entry";if(f==null){f=functions.getFunctionContaining(at);kind="recorded-containing";}
+          if(f!=null)database=Map.of("entryPoint",Long.toUnsignedString(f.getEntryPoint().getOffset(),16),"kind",kind,"recordedBodyContainsAddress",f.getBody().contains(at));
+        }
+        row.put("database",database);InsightPeRanges.Range range=null;
+        for(var candidate:scan.ranges())if(query.compareTo(candidate.begin())>=0&&query.compareTo(candidate.endExclusive())<0){range=candidate;break;}
+        row.put("boundary",range==null?null:range.facts());row.put("status","unresolved");
+        if(!complete)row.put("reason","boundary_lookup_"+scan.lookup().get("state"));
+        else if(range!=null&&database!=null&&!database.get("entryPoint").equals(range.begin().toString(16)))row.put("reason","boundary_conflict");
+        else if(range!=null){
+          String entry=range.begin().toString(16);
+          if(functions.getFunctionAt(space.getAddress(range.begin().longValue()))==null)row.put("reason","runtime_entry_not_defined");
+          else{row.put("status","resolved");row.put("entryPoint",entry);row.put("kind","pe-runtime-range");row.put("recordedBodyContainsAddress",database!=null&&Boolean.TRUE.equals(database.get("recordedBodyContainsAddress")));}
+        }else if(database!=null){row.put("status","resolved");row.put("entryPoint",database.get("entryPoint"));row.put("kind",database.get("kind"));row.put("recordedBodyContainsAddress",database.get("recordedBodyContainsAddress"));}
+        else row.put("reason","no_runtime_range_or_recorded_function");
+        items.put(word,row);
+      }
+      if(modification!=program.getModificationNumber())throw new IllegalStateException("Program changed during function-boundary lookup");
+      return Response.text(JSON.toJson(Map.of("protocol","insight-function-boundaries-v1","modification",Long.toString(modification),"boundaryLookup",scan.lookup(),"items",items)));
+    });
+  }
+}