@eyeauras/insight-cli 0.0.0-stage → 0.2.0

package/dist/src/saved-materials.js

@@ -0,0 +1,196 @@
+import { command, CliError, Permission } from '@eyeauras/cli-factory';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, opendir, realpath, rename, rm } from 'node:fs/promises';
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
+const maximumEntries = 100_000, maximumDepth = 128;
+function fail(code, message) { throw new CliError(message, { code: 'artifacts.' + code }); }
+function check(signal) { if (signal?.aborted)
+    fail('cancelled', 'Saving materials was cancelled; no snapshot was published.'); }
+function inside(parent, child) {
+    const value = relative(parent, child);
+    return value === '' || (!isAbsolute(value) && value !== '..' && !value.startsWith('..' + sep));
+}
+function stamp(info) { return [info.dev, info.ino, info.mode, info.size, info.mtimeNs, info.ctimeNs].join(':'); }
+async function syncDirectory(path) {
+    if (process.platform === 'win32')
+        return;
+    const handle = await open(path, constants.O_RDONLY);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function inventory(source, signal) {
+    const entries = [];
+    async function visit(path, name, depth) {
+        check(signal);
+        if (depth > maximumDepth || entries.length >= maximumEntries)
+            fail('limit', 'Materials exceed the traversal bound of 100000 entries or 128 directory levels; save a smaller selection.');
+        const info = await lstat(path, { bigint: true });
+        if (!info.isFile() && !info.isDirectory())
+            fail('unsupported', 'Materials must contain only ordinary files and directories; symbolic links and special files are unsupported.');
+        if (info.size > BigInt(Number.MAX_SAFE_INTEGER))
+            fail('limit', 'A materials entry exceeds the supported size counter.');
+        entries.push({ path: name, kind: info.isFile() ? 'file' : 'directory', stamp: stamp(info), size: Number(info.size) });
+        if (info.isDirectory()) {
+            // Sorting by code unit keeps manifest digests independent of locale and enumeration order.
+            const names = [];
+            for await (const child of await opendir(path)) {
+                check(signal);
+                if (names.length + entries.length >= maximumEntries)
+                    fail('limit', 'Materials exceed the traversal bound of 100000 entries; save a smaller selection.');
+                names.push(child.name);
+            }
+            names.sort();
+            for (const child of names)
+                await visit(join(path, child), name ? name + '/' + child : child, depth + 1);
+            if (stamp(await lstat(path, { bigint: true })) !== stamp(info))
+                fail('changed', 'Source changed while saving; save a stable file or directory.');
+        }
+    }
+    await visit(source, '', 0);
+    return entries;
+}
+async function verifyParents(source, entry, entries) {
+    let parent = entry.path ? entry.path.split('/').slice(0, -1).join('/') : undefined;
+    while (parent !== undefined) {
+        const expected = entries.get(parent);
+        if (stamp(await lstat(parent ? join(source, parent) : source, { bigint: true })) !== expected.stamp)
+            fail('changed', 'Source directory changed while saving; no snapshot was published.');
+        parent = parent ? parent.split('/').slice(0, -1).join('/') : undefined;
+    }
+}
+/** Copy user materials without initializing Ghidra, targets, sessions or Workspace. */
+export async function saveMaterials(appDataDirectory, source, signal) {
+    let stage, published;
+    try {
+        check(signal);
+        const sourcePath = resolve(source);
+        // Reject a symbolic source itself before resolving its parents (e.g. macOS /tmp).
+        const info = await lstat(sourcePath, { bigint: true });
+        if (!info.isFile() && !info.isDirectory())
+            fail('unsupported', 'Save an ordinary file or directory; symbolic links and special files are unsupported.');
+        const canonicalSource = await realpath(sourcePath);
+        await mkdir(appDataDirectory, { recursive: true, mode: 0o700 });
+        const appData = await realpath(appDataDirectory), storage = join(appData, 'materials');
+        if (info.isDirectory() && inside(canonicalSource, storage))
+            fail('recursive', 'Source contains the materials storage; choose a source outside its storage ancestry.');
+        await mkdir(storage, { recursive: true, mode: 0o700 });
+        if ((await lstat(storage)).isSymbolicLink() || await realpath(storage) !== storage)
+            fail('storage', 'Materials storage must be an ordinary profile-owned directory.');
+        const entries = await inventory(canonicalSource, signal), byPath = new Map(entries.map(entry => [entry.path, entry]));
+        if (entries[0].stamp !== stamp(info))
+            fail('changed', 'Source changed while preparing its snapshot; save a stable file or directory.');
+        const identity = randomUUID(), candidate = join(storage, '.pending-' + identity);
+        const final = join(storage, identity), content = join(candidate, 'content');
+        await mkdir(candidate, { mode: 0o700 });
+        stage = candidate;
+        await mkdir(content, { mode: 0o700 });
+        const name = basename(canonicalSource) || 'root', output = join(content, name);
+        const manifest = [], directories = [stage, content];
+        let files = 0, bytes = 0, fileDigest;
+        const buffer = Buffer.allocUnsafe(1024 * 1024);
+        for (const entry of entries) {
+            check(signal);
+            await verifyParents(canonicalSource, entry, byPath);
+            const inputPath = entry.path ? join(canonicalSource, entry.path) : canonicalSource;
+            const outputPath = entry.path ? join(output, entry.path) : output;
+            if (entry.kind === 'directory') {
+                await mkdir(outputPath, { mode: 0o700 });
+                directories.push(outputPath);
+                manifest.push({ path: entry.path, kind: 'directory' });
+                continue;
+            }
+            // NONBLOCK avoids a hang if a regular source is exchanged for a FIFO before open.
+            const input = await open(inputPath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            try {
+                const before = await input.stat({ bigint: true });
+                if (!before.isFile() || stamp(before) !== entry.stamp)
+                    fail('changed', 'Source file changed while saving; no snapshot was published.');
+                const destination = await open(outputPath, 'wx', 0o600), hash = createHash('sha256');
+                let copied = 0;
+                try {
+                    while (true) {
+                        check(signal);
+                        const { bytesRead } = await input.read(buffer, 0, buffer.length, copied);
+                        if (!bytesRead)
+                            break;
+                        copied += bytesRead;
+                        if (copied > entry.size)
+                            fail('changed', 'Source file grew while saving; no snapshot was published.');
+                        const chunk = buffer.subarray(0, bytesRead);
+                        hash.update(chunk);
+                        await destination.writeFile(chunk);
+                    }
+                    if (copied !== entry.size || stamp(await input.stat({ bigint: true })) !== entry.stamp ||
+                        stamp(await lstat(inputPath, { bigint: true })) !== entry.stamp)
+                        fail('changed', 'Source file changed while saving; no snapshot was published.');
+                    await destination.sync();
+                }
+                finally {
+                    await destination.close();
+                }
+                const sha256 = hash.digest('hex');
+                manifest.push({ path: entry.path, kind: 'file', bytes: copied, sha256 });
+                fileDigest = sha256;
+                files++;
+                bytes += copied;
+                if (!Number.isSafeInteger(bytes))
+                    fail('limit', 'Materials exceed the supported size counter.');
+            }
+            finally {
+                await input.close();
+            }
+        }
+        // Detect edits to earlier files and directory membership changes during the entire capture.
+        const after = await inventory(canonicalSource, signal);
+        if (JSON.stringify(after) !== JSON.stringify(entries) || await realpath(sourcePath) !== canonicalSource ||
+            stamp(await lstat(sourcePath, { bigint: true })) !== stamp(info))
+            fail('changed', 'Source changed while saving; no snapshot was published.');
+        const manifestBytes = JSON.stringify({ version: 1, entries: manifest }) + '\n';
+        const metadata = await open(join(stage, 'manifest.json'), 'wx', 0o600);
+        try {
+            await metadata.writeFile(manifestBytes);
+            await metadata.sync();
+        }
+        finally {
+            await metadata.close();
+        }
+        for (const directory of directories.reverse())
+            await syncDirectory(directory);
+        check(signal);
+        await rename(stage, final);
+        published = final;
+        stage = undefined;
+        await syncDirectory(storage);
+        return { state: 'saved', path: join(final, 'content', name), kind: entries[0].kind, files, bytes,
+            sha256: entries[0].kind === 'file' ? fileDigest : createHash('sha256').update(manifestBytes).digest('hex') };
+    }
+    catch (error) {
+        let cleanupFailed = false;
+        if (stage)
+            await rm(stage, { recursive: true, force: true }).catch(() => { cleanupFailed = true; });
+        // A directory-sync failure is not acknowledged as a durable save.
+        if (published)
+            await rm(published, { recursive: true, force: true }).catch(() => { cleanupFailed = true; });
+        if (error instanceof CliError) {
+            if (cleanupFailed)
+                throw new CliError(error.message + ' Some owned temporary files could not be removed; preserve the profile for cleanup.', { code: error.code });
+            throw error;
+        }
+        const code = error.code;
+        fail('save', `Could not save materials${code && /^[A-Z0-9_]+$/.test(code) ? ' (' + code + ')' : ''}; no complete snapshot was acknowledged.${cleanupFailed ? ' Some owned temporary files could not be removed; preserve the profile for cleanup.' : ''}`);
+    }
+}
+export function artifactsCommands() {
+    return [command('artifacts', 'Retain ordinary research files independently of analysis tools', [
+            command('save <path>', 'Save a complete independent copy of a file or directory in this profile', ({ args }, context) => {
+                if (typeof args.path !== 'string' || !args.path || args.path.includes('\0'))
+                    fail('invalid', 'Provide one file or directory path.');
+                return saveMaterials(context.appArguments.AppDataDirectory, resolve(context.cwd, args.path), context.signal);
+            }, { permission: Permission.Update }),
+        ])];
+}

package/dist/src/scripts.d.ts

@@ -0,0 +1,19 @@
+export interface ScriptItem {
+    script: string;
+    name: string;
+    language: 'Java' | 'Python';
+    origin: 'installation' | 'context' | 'extension';
+    category?: string;
+}
+export interface ScriptPage {
+    items: ScriptItem[];
+    count: number;
+    total: number;
+    offset: number;
+    limit: number;
+    truncated: boolean;
+}
+/** Resolve only an explicit inventory ID; native search paths never choose another script. */
+export declare function scriptPath(home: string, contextRoot: string, script: string, extensions?: string[]): Promise<string>;
+/** Enumerate configured installation and owned context scripts without exposing native paths. */
+export declare function scriptInventory(home: string, contextRoot: string, filter: string, limit: number, offset: number, extensions?: string[]): Promise<ScriptPage>;

package/dist/src/scripts.js

@@ -0,0 +1,79 @@
+import { readdir, open } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { constants } from 'node:fs';
+import { fail } from './model.js';
+/** Resolve only an explicit inventory ID; native search paths never choose another script. */
+export async function scriptPath(home, contextRoot, script, extensions = []) {
+    if (!/^(installation|context|extension):[^\0]+\.(java|py)$/.test(script) || script.includes('..') || script.includes('\\'))
+        fail('invalid', 'Choose an explicit script ID returned by ghidra scripts list.');
+    const page = await scriptInventory(home, contextRoot, script, 20000, 0, extensions), item = page.items.find(item => item.script === script);
+    if (!item)
+        fail('notFound', 'Script ID is absent from this context and installation.');
+    const part = script.slice(script.indexOf(':') + 1);
+    if (item.origin === 'extension') {
+        const [module, ...rest] = part.split('/'), root = extensions.find(p => p.split(/[\\/]/).pop() === module);
+        if (!root)
+            fail('binding', 'Script module is no longer enabled.');
+        return join(root, 'ghidra_scripts', ...rest);
+    }
+    if (item.origin === 'context')
+        return join(contextRoot, 'ghidra_scripts', part);
+    const segments = part.split('/'), filename = segments.pop();
+    return join(home, 'Ghidra', ...segments, 'ghidra_scripts', filename);
+}
+/** Enumerate configured installation and owned context scripts without exposing native paths. */
+export async function scriptInventory(home, contextRoot, filter, limit, offset, extensions = []) {
+    const items = [];
+    async function scripts(folder, origin, module) {
+        let entries;
+        try {
+            entries = await readdir(folder, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!entry.isFile() || !entry.name.endsWith('.java') && !entry.name.endsWith('.py'))
+                continue;
+            if (items.length >= 20000)
+                fail('limit', 'Script inventory exceeds 20000 entries.');
+            const name = entry.name, script = origin + ':' + (module ? module + '/' : '') + name;
+            const handle = await open(join(folder, name), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+            let category;
+            try {
+                const data = Buffer.alloc(4096), read = await handle.read(data, 0, data.length, 0);
+                if (!(await handle.stat()).isFile())
+                    fail('binding', 'Script inventory file changed during inspection.');
+                category = /^\s*(?:\/\/|#)\s*@category\s+([^\r\n]+)/m.exec(data.subarray(0, read.bytesRead).toString('utf8'))?.[1]?.trim().slice(0, 256);
+            }
+            finally {
+                await handle.close();
+            }
+            items.push({ script, name, language: name.endsWith('.java') ? 'Java' : 'Python', origin, ...(category ? { category } : {}) });
+        }
+    }
+    const installed = join(home, 'Ghidra');
+    async function modules(folder, depth) {
+        if (depth > 16)
+            fail('limit', 'Script module nesting exceeds 16 levels.');
+        for (const entry of (await readdir(folder, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!entry.isDirectory())
+                continue;
+            const path = join(folder, entry.name);
+            if (entry.name === 'ghidra_scripts')
+                await scripts(path, 'installation', relative(installed, folder).split(sep).join('/'));
+            else if (!['data', 'lib', 'os', 'src', 'docs'].includes(entry.name))
+                await modules(path, depth + 1);
+        }
+    }
+    await modules(installed, 0);
+    for (const root of extensions)
+        await scripts(join(root, 'ghidra_scripts'), 'extension', root.split(/[\\/]/).pop());
+    await scripts(join(contextRoot, 'ghidra_scripts'), 'context', '');
+    const matched = items.filter(item => !filter || [item.name, item.script, item.category ?? ''].some(value => value.toLowerCase().includes(filter.toLowerCase())))
+        .sort((a, b) => a.script.localeCompare(b.script));
+    const page = matched.slice(offset, offset + limit);
+    return { items: page, count: page.length, total: matched.length, offset, limit, truncated: offset + page.length < matched.length };
+}

package/dist/src/sdk-contracts.d.ts

@@ -0,0 +1,13 @@
+import type { Parameter } from './arguments.js';
+interface SdkOperation {
+    operation: string;
+    group: string;
+    name: string;
+    description: string;
+    write?: boolean;
+    pair?: boolean;
+    params: Parameter[];
+}
+export declare const sdkOperations: SdkOperation[];
+export declare const sdkWrites: Set<string>;
+export {};

package/dist/src/sdk-contracts.js

@@ -0,0 +1,37 @@
+const str = (name, required = true) => ({ name, type: 'string', required });
+const at = (name = 'address') => ({ ...str(name), semantic: 'address' });
+const json = (name, type = 'object', required = true) => ({ name, type, required });
+const count = (name, value) => ({ name, type: 'integer', required: false, default: value });
+const empty = (name) => ({ ...str(name, false), default: '', allowEmpty: true });
+const bool = (name) => ({ name, type: 'boolean', required: false, default: 'false' });
+const original = [str('name'), at('expect_start'), { ...count('expect_size', '1'), required: true }, str('expect_sha256')];
+export const sdkOperations = [
+    { operation: 'type-layout', group: 'types', name: 'layout', description: 'Read native packing, alignment, bitfields, settings and source archive identity', params: [str('path')] },
+    { operation: 'type-structure', group: 'types', name: 'define-layout', description: 'Create a native structure with packing/alignment/bitfields; replace only an explicitly selected empty placeholder', write: true, params: [str('path'), json('fields', 'array'), { name: 'packing', type: 'integer', required: false, default: '0' }, { name: 'alignment', type: 'integer', required: false, default: '0' }, bool('replace_placeholder')] },
+    { operation: 'type-settings', group: 'types', name: 'set-settings', description: 'Edit default settings by actual native definition names; null clears an explicit setting', write: true, params: [str('path'), json('settings')] },
+    { operation: 'type-archive-import', group: 'types', name: 'archive-import', description: 'Import explicit GDT type paths with archive identity and saved layout verification', write: true, params: [str('input'), json('types', 'array')] },
+    { operation: 'changes', group: 'changes', name: 'compare', description: 'Categorized native ProgramDiff of two saved private contexts; does not merge', pair: true, params: [{ ...json('categories', 'array', false), default: '["bytes","comments","symbols","functions"]' }, count('max_ranges', '100'), count('timeout_seconds', '30')] },
+    { operation: 'block-state', group: 'memory', name: 'block-state', description: 'Read exact block layout and bounded full-content digest', params: [str('name')] },
+    { operation: 'assembly-preview', group: 'assembly', name: 'preview', description: 'Assemble in this program language and processor context without writing', params: [at(), json('instructions', 'array')] },
+    { operation: 'patch-bytes', group: 'memory', name: 'patch-bytes', description: 'Replace equal-length bytes only when the expected bytes match; clears overlapping listing', write: true, params: [at(), str('expect_hex'), str('bytes_hex')] },
+    { operation: 'assemble', group: 'assembly', name: 'apply', description: 'Apply context-aware assembly with exact byte preconditions; clears overlapping listing', write: true, params: [at(), str('expect_hex'), json('instructions', 'array')] },
+    { operation: 'split-block', group: 'memory', name: 'split-block', description: 'Split one initialized block while verifying all original bytes and layout', write: true, params: [...original, at('split_address'), str('new_name')] },
+    { operation: 'move-block', group: 'memory', name: 'move-block', description: 'Move a block only when its original layout and bytes match', write: true, params: [...original, at()] },
+    { operation: 'join-blocks', group: 'memory', name: 'join-blocks', description: 'Join adjacent compatible blocks with independent content and size preconditions', write: true, params: [str('name'), str('second_name'), str('expect_sha256'), str('second_sha256'), { ...count('expect_size', '1'), required: true }, { ...count('second_size', '1'), required: true }] },
+    { operation: 'context-read', group: 'processor-context', name: 'read', description: 'Read bounded register-value ranges in the saved program context', params: [str('register'), at(), { ...at('end_address'), required: false }, count('limit', '100')] },
+    { operation: 'context-set', group: 'processor-context', name: 'set', description: 'Set a processor register value over at most 65536 bytes; requires unchanged-base publication', write: true, params: [str('register'), at(), at('end_address'), str('value')] },
+    { operation: 'context-clear', group: 'processor-context', name: 'clear', description: 'Remove an explicit processor register value over at most 65536 bytes', write: true, params: [str('register'), at(), at('end_address')] },
+    { operation: 'namespace-list', group: 'namespaces', name: 'list', description: 'List direct namespace/class children with explicit visited-symbol budget', params: [empty('parent'), count('limit', '100'), count('max_scan', '10000')] },
+    { operation: 'namespace-create', group: 'namespaces', name: 'create', description: 'Create an explicit namespace or class below an existing parent', write: true, params: [empty('parent'), str('name'), bool('class')] },
+    { operation: 'namespace-update', group: 'namespaces', name: 'update', description: 'Rename or reparent an ordinary namespace/class without recursive deletion', write: true, params: [str('path'), str('new_name'), empty('parent')] },
+    { operation: 'namespace-delete', group: 'namespaces', name: 'delete', description: 'Delete one empty ordinary namespace/class', write: true, params: [str('path')] },
+    { operation: 'external-list', group: 'externals', name: 'list', description: 'Read library identities or structured locations in one explicit library', params: [empty('library'), count('limit', '100')] },
+    { operation: 'library-create', group: 'externals', name: 'create-library', description: 'Create a named external library in the private program', write: true, params: [str('name')] },
+    { operation: 'library-update', group: 'externals', name: 'update-library', description: 'Rename an external library or change its logical project path', write: true, params: [str('name'), str('new_name', false), str('path', false)] },
+    { operation: 'library-delete', group: 'externals', name: 'delete-library', description: 'Delete an empty external library', write: true, params: [str('name')] },
+    { operation: 'external-create', group: 'externals', name: 'create-location', description: 'Create an external label/function with an optional memory address', write: true, params: [str('library'), str('label'), { ...at(), required: false }, bool('function')] },
+    { operation: 'external-update', group: 'externals', name: 'update-location', description: 'Rename/update one unambiguous external location', write: true, params: [str('library'), str('label'), str('new_label'), { ...at(), required: false }] },
+    { operation: 'external-delete', group: 'externals', name: 'delete-location', description: 'Delete one unambiguous external location, refusing retained dependencies', write: true, params: [str('library'), str('label')] },
+    { operation: 'decompiler-ir', group: 'decompiler', name: 'ir', description: 'Read bounded typed SSA P-code with explicit simplification/options and completion diagnostics', params: [at(), { ...str('simplification', false), default: 'decompile' }, count('max_ops', '1000'), count('timeout_seconds', '30'), bool('c_code'), { ...json('options', 'object', false), default: '{}' }] },
+];
+export const sdkWrites = new Set(sdkOperations.filter(v => v.write).map(v => '/sdk/' + v.operation));

package/dist/src/sdk-files.d.ts

@@ -0,0 +1,29 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { Workspace, type Scope } from './workspace.js';
+import { Research, type ResearchBackend } from './research.js';
+/** Native SDK file effects have retained input/output bytes and never repeat an uncertain call. */
+export declare class SdkFiles {
+    private readonly workspace;
+    private readonly research;
+    private readonly backend;
+    constructor(workspace: Workspace, research: Research, backend: () => Promise<ResearchBackend>);
+    loaders(input: string): Promise<{
+        inputSha256: string;
+    }>;
+    exporters(selected: Scope): Promise<{
+        value: Record<string, unknown>;
+        session: string;
+        target: string;
+    }>;
+    private copy;
+    private completedOutput;
+    databaseQuery(selected: Scope, operation: 'fid-query' | 'bsim-query', database: string, p: Record<string, unknown>): Promise<{
+        databaseSha256: string;
+        sourceSnapshotSha256: string;
+        value: Record<string, unknown>;
+        session: string;
+        target: string;
+    }>;
+    export(selected: Scope, operation: 'export' | 'archive-export' | 'fid-build' | 'bsim-build', parameters: Record<string, unknown>, directory: string, callerId?: string): Promise<unknown>;
+}
+export declare function sdkFileCommands(service: (c: CommandContext) => SdkFiles): CommandDefinition[];

package/dist/src/sdk-files.js

@@ -0,0 +1,249 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { mkdir, readdir, lstat, readFile, open, rename, copyFile, realpath, chmod } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { scope, address, number } from './research.js';
+import { object, fail, text, id, stable } from './model.js';
+import { parseDomainJson } from './json.js';
+import { selectedOptions } from './arguments.js';
+import { randomUUID } from 'node:crypto';
+async function persist(path, value) { const temp = path + '.new-' + randomUUID(), file = await open(temp, 'wx', 0o600); try {
+    await file.writeFile(stable(value));
+    await file.sync();
+}
+finally {
+    await file.close();
+} await rename(temp, path); if (process.platform !== 'win32') {
+    const directory = await open(dirname(path), 'r');
+    try {
+        await directory.sync();
+    }
+    finally {
+        await directory.close();
+    }
+} }
+/** Native SDK file effects have retained input/output bytes and never repeat an uncertain call. */
+export class SdkFiles {
+    workspace;
+    research;
+    backend;
+    constructor(workspace, research, backend) {
+        this.workspace = workspace;
+        this.research = research;
+        this.backend = backend;
+    }
+    async loaders(input) {
+        const artifact = await this.workspace.artifacts.capture(input, 'input'), backend = await this.backend();
+        if (!backend.sdkFile)
+            fail('configuration', 'Native SDK file workflows are unavailable.');
+        return { inputSha256: artifact.sha256, ...await backend.sdkFile('loaders', { input: await this.workspace.artifacts.verify(artifact) }) };
+    }
+    async exporters(selected) {
+        return this.research.ordered(selected, async () => {
+            const backend = await this.backend();
+            if (!backend.sdkFile)
+                fail('configuration', 'Native SDK file workflows are unavailable.');
+            await backend.open(selected);
+            const snapshot = await backend.saved(selected);
+            return { ...selected, value: await backend.sdkFile('exporters', { snapshot: await this.workspace.artifacts.verify(snapshot) }) };
+        });
+    }
+    async copy(files, directory, recovery = false) {
+        try {
+            await mkdir(directory, { mode: 0o700 });
+        }
+        catch (error) {
+            if (!recovery || error.code !== 'EEXIST')
+                throw error;
+        }
+        if (await realpath(directory) !== resolve(directory) || (await lstat(directory)).isSymbolicLink())
+            fail('binding', 'Export destination is not the requested ordinary directory.');
+        for (const file of files) {
+            if (!/^[a-zA-Z0-9_.-]{1,160}$/.test(file.name) || file.name === '.' || file.name === '..')
+                fail('binding', 'Exporter produced an unsupported output filename.');
+            const source = await this.workspace.artifacts.verify(file.artifact), output = join(directory, file.name);
+            try {
+                await copyFile(source, output, constants.COPYFILE_EXCL);
+            }
+            catch (error) {
+                if (!recovery || error.code !== 'EEXIST')
+                    throw error;
+            }
+            if ((await this.workspace.artifacts.capture(output, 'input')).id !== file.artifact.id)
+                fail('partial', 'Exported file bytes differ from retained native output.');
+            // Artifact copies retain their read-only mode. The owned user output needs a writable
+            // descriptor for FlushFileBuffers on Windows; verify existing recovery bytes first.
+            await chmod(output, 0o600);
+            const handle = await open(output, 'r+');
+            try {
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        if (process.platform !== 'win32')
+            for (const path of [directory, dirname(directory)]) {
+                const handle = await open(path, 'r');
+                try {
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+    }
+    async completedOutput(stage, request, operation) {
+        const marker = object(JSON.parse(await readFile(join(stage, 'native-result.json'), 'utf8')));
+        if (marker.request !== request || marker.operation !== operation || object(marker.value).state !== 'exported' || !Array.isArray(marker.files) || !marker.files.length || marker.files.length > 64)
+            fail('binding', 'Native file completion receipt differs from the retained request.');
+        const files = [];
+        for (const item of marker.files) {
+            const row = object(item), name = text(row.name, 160);
+            if (!/^[a-zA-Z0-9_.-]+$/.test(name) || name === '.' || name === '..')
+                fail('binding', 'Native output name is not a simple owned file.');
+            const path = join(stage, 'outputs', name);
+            if (!(await lstat(path)).isFile() || (await lstat(path)).isSymbolicLink())
+                fail('binding', 'Native output is not a regular owned file.');
+            const artifact = await this.workspace.artifacts.capture(path, 'input');
+            if (artifact.sha256 !== row.sha256 || artifact.size !== row.size)
+                fail('partial', 'Native output changed after its completion receipt.');
+            files.push({ name, artifact });
+        }
+        return { files, value: marker.value };
+    }
+    async databaseQuery(selected, operation, database, p) {
+        const artifact = await this.workspace.artifacts.capture(database, 'input');
+        if (artifact.size > 268435456)
+            fail('limit', 'Function database exceeds 256 MiB.');
+        return this.research.ordered(selected, async () => {
+            const backend = await this.backend();
+            if (!backend.sdkFile)
+                fail('configuration', 'Native function databases are unavailable.');
+            await backend.open(selected);
+            const snapshot = await backend.saved(selected), value = await backend.sdkFile(operation, { ...p, database: await this.workspace.artifacts.verify(artifact), snapshot: await this.workspace.artifacts.verify(snapshot) });
+            return { ...selected, databaseSha256: artifact.sha256, sourceSnapshotSha256: snapshot.sha256, value };
+        });
+    }
+    async export(selected, operation, parameters, directory, callerId) {
+        const reserved = this.workspace.reserveRequest(selected, 'ghidra.sdk-file.' + operation, { ...parameters, outputDirectory: directory }, callerId);
+        return this.research.ordered(selected, async () => {
+            const request = this.workspace.request(reserved.request.id), stage = join(this.workspace.directory, 'sdk-exports', request.id), receiptPath = join(stage, 'receipt.json');
+            if (reserved.replay && request.state !== 'accepted') {
+                if (request.state === 'applied')
+                    return request.result;
+                let saved;
+                try {
+                    saved = object(JSON.parse(await readFile(receiptPath, 'utf8')));
+                }
+                catch {
+                    let completed;
+                    try {
+                        completed = await this.completedOutput(stage, request.id, operation);
+                    }
+                    catch {
+                        fail('unknown', 'Native export has no verified completed receipt; the original call is not repeated.');
+                    }
+                    saved = { request: request.id, operation, ...completed };
+                    await persist(receiptPath, saved);
+                }
+                if (saved.request !== request.id || saved.operation !== operation || !Array.isArray(saved.files))
+                    fail('binding', 'Native export receipt differs from the retained intent.');
+                const files = saved.files;
+                await this.copy(files, directory, true);
+                const current = this.workspace.context(selected);
+                const result = { ...selected, state: 'exported', outputDirectory: directory, files: files.map(file => ({ name: file.name, sha256: file.artifact.sha256, size: file.artifact.size })), value: saved.value };
+                this.workspace.completeSavedRequest(selected, request.id, current.generation, {}, result);
+                return result;
+            }
+            try {
+                await lstat(directory);
+                fail('exists', 'Export directory already exists; choose a new directory.');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            const backend = await this.backend();
+            if (!backend.sdkFile)
+                fail('configuration', 'Native SDK file workflows are unavailable.');
+            await backend.open(selected);
+            const snapshot = await backend.saved(selected), current = this.workspace.context(selected);
+            await mkdir(stage, { recursive: true, mode: 0o700 });
+            const outputs = join(stage, 'outputs');
+            await mkdir(outputs, { recursive: true, mode: 0o700 });
+            if (await realpath(outputs) !== resolve(outputs) || (await lstat(outputs)).isSymbolicLink() || (await readdir(outputs)).length)
+                fail('binding', 'Accepted file preparation must retain an empty owned output directory.');
+            this.workspace.startRequest(request.id, { kind: 'sdk-file', operation, snapshot, generation: current.generation });
+            try {
+                const filename = operation === 'archive-export' ? 'types.gdt' : operation === 'fid-build' ? 'database.fidb' : operation === 'bsim-build' ? 'database.mv.db' : 'program.out';
+                const value = await backend.sdkFile(operation, { ...parameters, request_id: request.id, receipt: join(stage, 'native-result.json'), snapshot: await this.workspace.artifacts.verify(snapshot), output: join(outputs, filename) });
+                if (value.state !== 'exported')
+                    fail('partial', 'Native exporter did not establish a completed output.');
+                const completed = await this.completedOutput(stage, request.id, operation), files = completed.files;
+                if (stable(completed.value) !== stable(value))
+                    fail('partial', 'Native file reply differs from its durable receipt.');
+                await persist(receiptPath, { request: request.id, operation, files, value });
+                await this.copy(files, directory);
+                const result = { ...selected, state: 'exported', outputDirectory: directory, files: files.map(file => ({ name: file.name, sha256: file.artifact.sha256, size: file.artifact.size })), value };
+                this.workspace.completeSavedRequest(selected, request.id, current.generation, { workingSnapshot: snapshot }, result);
+                return result;
+            }
+            catch (error) {
+                this.workspace.recordRequest(request.id, 'unknown', { ...selected, state: 'unknown' });
+                throw error;
+            }
+        });
+    }
+}
+function json(value) { return parseDomainJson(text(value, 16000)); }
+export function sdkFileCommands(service) {
+    const outputs = [...selectedOptions, { flags: '--output-directory <directory>', description: 'New output directory including all exporter companion files', required: true },
+        { flags: '--request-id <id>', description: 'Retrieve retained export bytes without repeating native export' }];
+    const databases = [];
+    for (const kind of ['fid', 'bsim']) {
+        databases.push(command('build-' + kind, 'Build a genuine native ' + kind + ' database from the saved private snapshot', ({ options: o }, c) => service(c).export(scope(o), kind + '-build', { library: text(o.library, 512), ...(kind === 'fid' ? { version: text(o.libraryVersion, 128) } : {}) }, resolve(c.cwd, text(o.outputDirectory, 4096)), o.requestId === undefined ? undefined : id(o.requestId)), { permission: Permission.Update, options: [...outputs, { flags: '--library <name>', description: 'Native library/database name', required: true }, ...(kind === 'fid' ? [{ flags: '--library-version <version>', description: 'Native library version', required: true }] : [])] }));
+        databases.push(command(kind + '-query', 'Query one explicitly consumed native ' + kind + ' database with provenance and no-match semantics', ({ options: o }, c) => {
+            const p = { limit: number(o.limit, 1000, 1) };
+            if (o.function !== undefined)
+                p.function = address(o.function);
+            if (kind === 'fid') {
+                const threshold = Number(o.threshold);
+                if (!Number.isFinite(threshold) || threshold < 0 || threshold > 100000)
+                    fail('invalid', 'FID threshold must be 0–100000 native code units.');
+                p.threshold = threshold;
+            }
+            else {
+                const similarity = Number(o.similarity), significance = Number(o.significance);
+                if (!Number.isFinite(similarity) || similarity < 0 || similarity > 1 || !Number.isFinite(significance) || significance < 0 || significance > 1000000)
+                    fail('invalid', 'Invalid native BSim similarity/significance threshold.');
+                p.similarity = similarity;
+                p.significance = significance;
+            }
+            return service(c).databaseQuery(scope(o), kind + '-query', resolve(c.cwd, text(o.database, 4096)), p);
+        }, { permission: Permission.ReadOnly, options: [...selectedOptions, { flags: '--database <file>', description: 'Native FID or BSim/H2 file; immutable bytes are consumed first', required: true },
+                { flags: '--function <address>', description: 'Exact function entry', ...(kind === 'bsim' ? { required: true } : {}) }, { flags: '--limit <count>', description: 'Maximum returned matches', defaultValue: 20 },
+                ...(kind === 'fid' ? [{ flags: '--threshold <score>', description: 'Native matching code-unit threshold', defaultValue: 14.6 }] : [{ flags: '--similarity <number>', description: 'Native feature similarity 0–1', defaultValue: 0.7 }, { flags: '--significance <number>', description: 'Native feature significance', defaultValue: 0 }])] }));
+    }
+    return [command('libraries', 'Native FID and BSim/H2 library identity/similarity databases', databases), command('formats', 'Native loaders and exporters', [
+            command('loaders', 'Read installed loader names and supported specs/options for consumed bytes', ({ options: o }, c) => service(c).loaders(resolve(c.cwd, text(o.input, 4096))), { permission: Permission.ReadOnly, options: [{ flags: '--input <file>', description: 'Input file to inspect', required: true }] }),
+            command('exporters', 'Read installed exporters and their actual options for this program', ({ options: o }, c) => service(c).exporters(scope(o)), { permission: Permission.ReadOnly, options: selectedOptions }),
+            command('export', 'Export through an explicitly selected native exporter with typed options/ranges', ({ options: o }, c) => {
+                const p = { exporter: text(o.exporter, 512), options: object(json(o.options)) };
+                if (o.ranges !== undefined) {
+                    const ranges = json(o.ranges);
+                    if (!Array.isArray(ranges) || !ranges.length || ranges.length > 64)
+                        fail('invalid', 'Export ranges require 1–64 start/end objects.');
+                    p.ranges = ranges;
+                }
+                return service(c).export(scope(o), 'export', p, resolve(c.cwd, text(o.outputDirectory, 4096)), o.requestId === undefined ? undefined : id(o.requestId));
+            }, { permission: Permission.Update, options: [...outputs, { flags: '--exporter <id>', description: 'Explicit native exporter name/ID', required: true }, { flags: '--options <json>', description: 'Named primitive native options', defaultValue: '{}' }, { flags: '--ranges <json>', description: 'Address ranges with start/end; exporter must support restricted output' }] }),
+        ]), command('types', 'Native type archives', [
+            command('archive-export', 'Export 1–256 explicit type paths to a native GDT with checked layout', ({ options: o }, c) => {
+                const types = json(o.types);
+                if (!Array.isArray(types) || !types.length || types.length > 256 || types.some(v => typeof v !== 'string' || !v.startsWith('/')))
+                    fail('invalid', 'Types must be 1–256 absolute type paths.');
+                return service(c).export(scope(o), 'archive-export', { types }, resolve(c.cwd, text(o.outputDirectory, 4096)), o.requestId === undefined ? undefined : id(o.requestId));
+            }, { permission: Permission.Update, options: [...outputs, { flags: '--types <json>', description: 'Selected native type paths', required: true }] }),
+        ])];
+}