@eyeauras/insight-cli 0.3.2 → 0.4.0

package/dist/src/research.js

@@ -1,11 +1,16 @@
 import { textWindow } from './text-window.js';
 import { functionResult, functionFailure } from './function-results.js';
 import { inspectFunctions } from './function-inspection.js';
+import { entryRequest } from './function-entries.js';
+import { inspectAnchors } from './string-anchors.js';
 import { fail, id, object, text, digest } from './model.js';
 import { fieldKey, scalarMerge, scalarRefresh } from './merge.js';
 import { verifyMutation } from './mutation-effects.js';
 import { transferResult } from './cross-results.js';
 import { CliError } from '@eyeauras/cli-factory';
+import { timed } from './internal-timing.js';
+import { navigationResult } from './context-diagnostics.js';
+import { inspectCodeReferences } from './code-references.js';
 export function address(value) {
     const input = text(value, 128);
     const match = /^(?:([A-Za-z0-9_]+):)?(?:0x)?([a-fA-F0-9]+)$/.exec(input);
@@ -66,7 +71,7 @@ export class Research {
     }
     async ordered(selected, action) {
         const key = this.workspace.context(selected).id, previous = this.tasks.get(key);
-        const task = (previous ? previous.catch(() => { }) : Promise.resolve()).then(action);
+        const task = timed('facade.queue', 'research', async () => { await previous?.catch(() => { }); }).then(action);
         this.tasks.set(key, task);
         try {
             return await task;
@@ -77,7 +82,7 @@ export class Research {
         }
     }
     async boundary(selected, action) {
-        const key = 'command:' + this.workspace.context(selected).id, previous = this.tasks.get(key), task = (previous ? previous.catch(() => { }) : Promise.resolve()).then(action);
+        const key = 'command:' + this.workspace.context(selected).id, previous = this.tasks.get(key), task = timed('facade.queue', 'command', async () => { await previous?.catch(() => { }); }).then(action);
         this.tasks.set(key, task);
         try {
             return await task;
@@ -147,10 +152,14 @@ export class Research {
                 return opened(request.result);
             if (reserved.replay && request.state !== 'accepted')
                 throw new CliError('This open retains an unproved outcome; inspect the retained context before continuing.', { code: 'coordinator.unknown', result: retained(request.state), next });
-            if (this.workspace.unresolved(reserved.context).some(other => other.id !== request.id)) {
+            const unresolved = this.workspace.unresolved(reserved.context).filter(other => other.id !== request.id);
+            if (unresolved.length) {
                 const result = { session: reserved.context.session, target, state: 'blocked' };
                 this.workspace.recordRequest(request.id, 'failed', result);
-                fail('blocked', 'This context retains an unproved effect; continuation did not start a second operation.', result);
+                const close = unresolved.find(other => other.operation === 'ghidra.close');
+                throw new CliError('This context retains an unproved effect; continuation did not start a second operation.', {
+                    code: 'coordinator.blocked', result, next: close ? [['ghidra', 'close', '--session', reserved.context.session, '--target', target, '--request-id', close.callerId ?? close.id]] : next
+                });
             }
             this.workspace.startRequest(request.id);
             try {
@@ -292,13 +301,48 @@ export class Research {
         });
     }
     async inspectFunctions(selected, parameters, options) {
+        const lookup = entryRequest(parameters, options);
         return this.ordered(selected, async () => {
             const backend = await this.backend();
             await backend.open(selected);
             const context = this.workspace.context(selected);
-            const observation = await backend.observation?.(selected);
+            const observe = backend.inspectObservation ? () => backend.inspectObservation(selected) : backend.observation ? () => backend.observation(selected) : undefined;
+            if (lookup && !observe)
+                fail('unsupported', 'Address resolution requires guarded native observations.');
+            const observation = await observe?.();
             const view = { revision: revision(context.baseRevision), identity: digest({ target: selected.target, context: context.id, generation: context.generation, snapshot: context.workingSnapshot, epoch: context.viewEpoch ?? 0, observation }) };
-            return inspectFunctions(backend, selected, parameters, options, view, observation);
+            return inspectFunctions(backend, selected, parameters, options, view, observation, observe);
+        });
+    }
+    async stringAnchors(selected, request) {
+        return this.ordered(selected, async () => {
+            const backend = await this.backend();
+            await backend.open(selected);
+            const observe = backend.inspectObservation ? () => backend.inspectObservation(selected) : backend.observation ? () => backend.observation(selected) : undefined;
+            if (!observe)
+                fail('unsupported', 'String anchors require guarded native observations.');
+            const context = this.workspace.context(selected), observation = await observe();
+            const view = digest({ target: selected.target, context: context.id, generation: context.generation, snapshot: context.workingSnapshot, epoch: context.viewEpoch ?? 0, observation });
+            return inspectAnchors(backend, selected, request, view, observation, observe);
+        });
+    }
+    async codeReferences(selected, request) {
+        return this.ordered(selected, async () => {
+            const backend = await this.backend();
+            await backend.open(selected);
+            if (!backend.observation)
+                fail('unsupported', 'Code-reference continuation requires native view observation.');
+            const context = this.workspace.context(selected), observation = await backend.observation(selected);
+            const view = digest({ target: selected.target, context: context.id, generation: context.generation, snapshot: context.workingSnapshot, epoch: context.viewEpoch ?? 0, observation });
+            return inspectCodeReferences(backend, selected, request, view, observation);
+        });
+    }
+    async navigation(selected, maximum) {
+        return this.ordered(selected, async () => {
+            const backend = await this.backend();
+            await backend.open(selected);
+            const value = navigationResult(await backend.call(selected, '/navigation_diagnostic', { max_scan: maximum }), maximum);
+            return { ...selected, value: { ...value, initialAnalysis: this.workspace.model(selected.target).settings.autoAnalyze ? 'requested' : 'none', priorAnalysis: 'unknown', provenance: 'Initial facade policy only; imported/saved metadata may have an unknown analysis history.' } };
         });
     }
     async xrefs(selected, at, limit, offset) {
@@ -428,6 +472,9 @@ export class Research {
                 this.tasks.delete(key);
         }
     }
+    async reconcileRequests(selected, backend) {
+        return this.sharedOrder(selected.target, () => this.reconcile(selected, backend));
+    }
     async reconcile(selected, backend) {
         const active = this.workspace.activePublication(selected.target);
         if (active) {
@@ -541,7 +588,7 @@ export class Research {
                     if (!await backend.closed(selected))
                         continue;
                     const current = this.workspace.context(selected);
-                    this.workspace.completeSavedRequest(selected, request.id, current.generation, {}, { ...selected, state: 'closed', pendingChanges: count(current) });
+                    this.workspace.completeSavedRequest(selected, request.id, current.generation, { state: 'stopped' }, { ...selected, state: 'closed', pendingChanges: count(current) });
                 }
                 catch { /* A stopped metadata flag alone never proves process release. */ }
                 continue;
@@ -794,6 +841,10 @@ export class Research {
             if (reserved.replay && request.state !== 'accepted') {
                 if (request.state === 'applied')
                     return request.result;
+                if (operation === '/run_script_inline' && request.state === 'failed' && object(request.result ?? {}).reason === 'script_not_executed') {
+                    const result = object(request.result), execution = object(result.execution);
+                    fail('script.' + String(execution.stage), String(object(result.diagnostic).message), result);
+                }
                 if (operation.startsWith('/sdk/') && request.state === 'failed' && object(request.result ?? {}).state === 'rejected')
                     fail('rejected', 'This SDK transaction was rolled back and is not repeated.', request.result);
                 fail('unknown', 'This saved-state operation retains an unresolved outcome; it is not re-executed.', request.result);
@@ -807,7 +858,24 @@ export class Research {
                 savedVerification: !!verifySaved });
             let savedSnapshot, phase = 'operation';
             try {
-                const raw = await backend.call(selected, operation, parameters), response = raw && typeof raw === 'object' && !Array.isArray(raw) ? object(raw) : { output: raw };
+                let raw;
+                if (operation === '/run_script_inline' && backend.inlineScript) {
+                    const attempt = await backend.inlineScript(selected, parameters, request.id);
+                    raw = attempt.response;
+                    if (attempt.response.success === false) {
+                        const result = { ...selected, requestId: request.callerId ?? request.id, state: attempt.safe ? 'rejected' : 'unknown',
+                            contextState: attempt.safe ? 'ready' : 'needs_recovery', reason: attempt.safe ? 'script_not_executed' : 'script_execution_not_proven_complete',
+                            execution: attempt.response.execution, diagnostic: attempt.response.diagnostic, diagnostics: attempt.response.diagnostics,
+                            diagnosticsTruncated: attempt.response.diagnosticsTruncated, compilerOutput: attempt.response.compilerOutput,
+                            output: attempt.response.console_output, outputTruncated: attempt.response.outputTruncated };
+                        if (attempt.safe)
+                            this.workspace.recordRequest(request.id, 'failed', result);
+                        fail('script.' + String(object(attempt.response.execution).stage), String(object(attempt.response.diagnostic).message), result);
+                    }
+                }
+                else
+                    raw = await backend.call(selected, operation, parameters);
+                const response = raw && typeof raw === 'object' && !Array.isArray(raw) ? object(raw) : { output: raw };
                 if (['rejected', 'partial', 'failed', 'error'].includes(String(response.status)) || response.success === false)
                     fail('partial', 'Program operation reported a rejected or incomplete effect.');
                 if (!verifySaved && response.success !== true && response.status !== 'success')
@@ -825,6 +893,8 @@ export class Research {
                 return result;
             }
             catch (error) {
+                if (operation === '/run_script_inline' && this.workspace.request(request.id).state === 'failed' && object(this.workspace.request(request.id).result ?? {}).reason === 'script_not_executed')
+                    throw error;
                 if (operation.startsWith('/sdk/') && String(error.code).endsWith('.rejected')) {
                     this.workspace.recordRequest(request.id, 'failed', { ...selected, state: 'rejected', reason: 'native_transaction_rolled_back' });
                     throw error;

package/dist/src/string-anchors.d.ts

@@ -0,0 +1,43 @@
+import { type CommandContext } from '@eyeauras/cli-factory';
+import { type Research, type ResearchBackend } from './research.js';
+import type { Scope } from './workspace.js';
+export declare const anchorAlgorithm = "raw-string-anchors-v1";
+export declare const anchorEncodings: readonly ["ascii", "utf16le"];
+type Encoding = typeof anchorEncodings[number];
+interface Frontier {
+    address: string;
+    encoding: Encoding;
+}
+interface Query {
+    text: string;
+    encodings: Encoding[];
+    start: string;
+    end: string;
+    cap: number;
+}
+interface Budgets {
+    max_bytes: number;
+    max_candidates: number;
+    timeout_seconds: number;
+    limit: number;
+}
+export interface AnchorRequest {
+    query: Query;
+    from: Frontier;
+    budgets: Budgets;
+    expectedView?: string;
+}
+export declare function anchorRequest(o: Record<string, unknown>, who: Scope): AnchorRequest;
+export declare function anchorResult(raw: unknown, r: AnchorRequest, modification: string): Record<string, unknown>;
+export declare function inspectAnchors(backend: ResearchBackend, who: Scope, r: AnchorRequest, view: string, observation: unknown, observe: () => Promise<unknown>): Promise<{
+    value: {
+        view: {
+            identity: string;
+        };
+        cursor: string | null;
+    };
+    session: string;
+    target: string;
+}>;
+export declare function stringAnchorCommands(research: (c: CommandContext) => Research): import("@eyeauras/cli-factory").CommandDefinition[];
+export {};

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.2",
+  "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);
+  }
+}