@eyeauras/insight-cli 0.0.0-stage → 0.2.0

package/dist/src/ui.js

@@ -0,0 +1,88 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { scope, address, number } from './research.js';
+import { id, text, object, fail } from './model.js';
+import { selectedOptions } from './arguments.js';
+export class UserInterface {
+    workspace;
+    research;
+    backend;
+    constructor(workspace, research, backend) {
+        this.workspace = workspace;
+        this.research = research;
+        this.backend = backend;
+    }
+    async read(selected, operation, facet = 'all') {
+        return this.research.ordered(selected, async () => {
+            const backend = await this.backend();
+            await backend.open(selected);
+            if (operation === 'tools' || operation === 'plugins_list')
+                await backend.mode(selected, 'gui');
+            if (!backend.ui)
+                fail('configuration', 'Selected backend lacks the UI adapter.');
+            const value = await backend.ui(selected, operation, {});
+            return { ...selected, value: operation === 'cursor' && facet !== 'all' ? { [facet]: value[facet], ...(value[facet] === null ? { reason: value[facet + '_unavailable'] } : {}) } : value };
+        });
+    }
+    async change(selected, operation, p, callerId) {
+        const reserved = this.workspace.reserveRequest(selected, 'ghidra.ui.' + operation, p, callerId);
+        return this.research.ordered(selected, async () => {
+            const request = this.workspace.request(reserved.request.id);
+            if (reserved.replay && request.state !== 'accepted') {
+                if (request.state === 'applied')
+                    return request.result;
+                fail('unknown', 'UI effect is retained and is not repeated.', request.result);
+            }
+            const backend = await this.backend();
+            await backend.open(selected);
+            await backend.mode(selected, 'gui');
+            if (!backend.ui)
+                fail('configuration', 'Selected backend lacks the UI adapter.');
+            const context = this.workspace.context(selected);
+            this.workspace.startRequest(request.id, { kind: 'ui', operation, generation: context.generation });
+            try {
+                const value = await backend.ui(selected, operation, p);
+                if (operation === 'goto') {
+                    const cursor = await backend.ui(selected, 'cursor', {}), location = object(cursor.address);
+                    if (location.session !== selected.session || location.target !== selected.target || address(location.address) !== address(p.address))
+                        fail('partial', 'Cursor did not reach the requested context and address.');
+                }
+                const plugin = operation === 'plugins_set', snapshot = plugin ? await backend.saved(selected) : undefined;
+                const complexChanges = plugin ? [...context.complexChanges, request.id] : context.complexChanges;
+                const result = { ...selected, state: 'applied', value, ...(plugin ? { sharedState: 'pending', pendingChanges: context.scalars.length + complexChanges.length } : {}) };
+                this.workspace.completeSavedRequest(selected, request.id, context.generation, plugin ? { workingSnapshot: snapshot, complexChanges } : {}, result);
+                return result;
+            }
+            catch (error) {
+                this.workspace.recordRequest(request.id, 'unknown', { ...selected, state: 'unknown', operation });
+                throw error;
+            }
+        });
+    }
+}
+export function uiCommands(service) {
+    const request = { flags: '--request-id <id>', description: 'Retrieve the recorded UI result without repeating it' };
+    return [command('ui', 'Inspect and control the selected context interface', [
+            command('cursor', 'Read the focused address, function, selection and program', ({ options: o }, c) => {
+                const type = text(o.type);
+                if (!['all', 'address', 'function', 'selection', 'program'].includes(type))
+                    fail('invalid', 'Cursor type must be all, address, function, selection or program.');
+                return service(c).read(scope(o), 'cursor', type);
+            }, { permission: Permission.ReadOnly, options: [...selectedOptions, { flags: '--type <facet>', description: 'Cursor facet or all', defaultValue: 'all' }] }),
+            command('tools', 'Read tools in the owned GUI context', ({ options: o }, c) => service(c).read(scope(o), 'tools'), { permission: Permission.ReadOnly, options: selectedOptions }),
+            command('goto', 'Navigate the owned browser and verify the cursor', ({ options: o }, c) => service(c).change(scope(o), 'goto', { address: address(o.address) }, o.requestId === undefined ? undefined : id(o.requestId)), { permission: Permission.Update, options: [...selectedOptions, { flags: '--address <address>', description: 'Explicit address', required: true }, request] }),
+            command('prompt-policy', 'Temporarily control the owned GUI prompt policy', ({ options: o }, c) => {
+                const action = text(o.action);
+                if (!['status', 'enable', 'disable'].includes(action))
+                    fail('invalid', 'Prompt policy action must be status, enable or disable.');
+                return service(c).change(scope(o), 'prompt_policy', { action, reason: text(o.reason, 512), seconds: number(o.seconds, 300, 1) }, o.requestId === undefined ? undefined : id(o.requestId));
+            }, { permission: Permission.Update, options: [...selectedOptions, { flags: '--action <action>', description: 'status, enable or disable', defaultValue: 'status' },
+                    { flags: '--reason <text>', description: 'Recorded policy reason', defaultValue: 'automation' }, { flags: '--seconds <count>', description: 'Requested duration (1–300 seconds)', defaultValue: 120 }, request] }),
+        ])];
+}
+export function pluginCommands(service) {
+    return [command('plugins', 'Configure plugins from enabled managed modules in an owned GUI', [
+            command('list', 'Read enabled managed plugins in this GUI tool', ({ options: o }, c) => service(c).read(scope(o), 'plugins_list'), { permission: Permission.ReadOnly, options: selectedOptions }),
+            command('set', 'Enable or disable one installed managed plugin with immediate readback', ({ options: o }, c) => { if (o.enabled !== 'true' && o.enabled !== 'false')
+                fail('invalid', 'enabled must be true or false.'); return service(c).change(scope(o), 'plugins_set', { plugin: text(o.plugin, 512), enabled: o.enabled === 'true' }, o.requestId === undefined ? undefined : id(o.requestId)); }, { permission: 'Destructive', options: [...selectedOptions, { flags: '--plugin <class>', description: 'Managed plugin ID from extensions capabilities', required: true }, { flags: '--enabled <boolean>', description: 'true or false', required: true }, { flags: '--request-id <id>', description: 'Retrieve the original plugin outcome without replay' }] })
+        ])];
+}

package/dist/src/utility.d.ts

@@ -0,0 +1,14 @@
+import { type CommandDefinition } from '@eyeauras/cli-factory';
+/** Equivalent of the pinned unsigned 64-bit number conversion, without a tool process. */
+export declare function convertNumber(input: unknown, size?: unknown): {
+    input: string;
+    input_type: string;
+    size: number;
+    decimal_unsigned: string;
+    decimal_signed: string;
+    hexadecimal: string;
+    binary: string;
+    octal: string;
+    hex_padded: string;
+};
+export declare function utilityCommands(): CommandDefinition[];

package/dist/src/utility.js

@@ -0,0 +1,43 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { fail, text } from './model.js';
+/** Equivalent of the pinned unsigned 64-bit number conversion, without a tool process. */
+export function convertNumber(input, size = 4) {
+    const source = text(input, 128), width = Number(size);
+    if (!Number.isSafeInteger(width) || width < 1 || width > 8)
+        fail('invalid', 'Size must be 1–8 bytes.');
+    let value, inputType;
+    try {
+        if (/^0[xX][a-fA-F0-9]+$/.test(source)) {
+            value = BigInt(source);
+            inputType = 'hexadecimal';
+        }
+        else if (/^0[bB][01]+$/.test(source)) {
+            value = BigInt(source);
+            inputType = 'binary';
+        }
+        else if (/^0[0-7]+$/.test(source) && source.length > 1) {
+            value = BigInt('0o' + source);
+            inputType = 'octal';
+        }
+        else if (/^\+?\d+$/.test(source)) {
+            value = BigInt(source);
+            inputType = 'decimal';
+        }
+        else
+            throw Error();
+        if (value < 0n || value > 0xffffffffffffffffn)
+            throw Error();
+    }
+    catch {
+        fail('invalid', 'Number must be an unsigned 64-bit decimal, hexadecimal, binary or octal integer.');
+    }
+    const bits = BigInt(width * 8), masked = value & ((1n << bits) - 1n), signed = masked >= (1n << (bits - 1n)) ? masked - (1n << bits) : masked, hex = masked.toString(16).toUpperCase();
+    return { input: source, input_type: inputType, size: width, decimal_unsigned: masked.toString(), decimal_signed: signed.toString(),
+        hexadecimal: '0x' + hex, binary: '0b' + masked.toString(2), octal: '0' + masked.toString(8), hex_padded: '0x' + hex.padStart(width * 2, '0') };
+}
+export function utilityCommands() {
+    return [command('utility', 'Stateless research utilities', [
+            command('convert-number', 'Convert an unsigned 64-bit integer at an explicit byte width', ({ options: o }) => convertNumber(o.text, o.size), { permission: Permission.ReadOnly, options: [{ flags: '--text <number>', description: 'Decimal, 0x hexadecimal, 0b binary or leading-zero octal', required: true },
+                    { flags: '--size <bytes>', description: 'Output width, 1–8 bytes', defaultValue: 4 }] })
+        ])];
+}

package/dist/src/version-tracking.d.ts

@@ -0,0 +1,57 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { Workspace, type Scope } from './workspace.js';
+import { Research, type ResearchBackend } from './research.js';
+/** A native VT object belongs to an existing research session; it is not another agent session. */
+export declare class VersionTracking {
+    private readonly workspace;
+    private readonly research;
+    private readonly backend;
+    private readonly tasks;
+    constructor(workspace: Workspace, research: Research, backend: () => Promise<ResearchBackend>, tasks: Map<string, Promise<unknown>>);
+    private ordered;
+    private root;
+    private owner;
+    private response;
+    private native;
+    list(selected: Scope, offset: number, limit: number): Promise<{
+        items: never[];
+        complete: boolean;
+        session: string;
+        target: string;
+    } | {
+        nextOffset?: number | undefined;
+        items: {
+            tracking: string;
+            source: Scope;
+            destination: Scope;
+            sourceSnapshotSha256: string;
+            destinationSnapshotSha256: string;
+        }[];
+        visited: number;
+        complete: boolean;
+        session: string;
+        target: string;
+    }>;
+    private decisionResult;
+    create(selected: Scope, source: Scope, callerId?: string): Promise<unknown>;
+    read(selected: Scope, tracking: string, operation: 'matches' | 'markup', p: Record<string, unknown>): Promise<{
+        tracking: string;
+        source: {
+            snapshotSha256: string;
+            session: string;
+            target: string;
+        };
+        destination: {
+            snapshotSha256: string;
+            session: string;
+            target: string;
+        };
+        sourceContextChanged: boolean;
+        destinationContextChanged: boolean;
+        value: unknown;
+        session: string;
+        target: string;
+    }>;
+    decide(selected: Scope, tracking: string, p: Record<string, unknown>, callerId?: string): Promise<unknown>;
+}
+export declare function trackingCommands(service: (c: CommandContext) => VersionTracking): CommandDefinition[];

package/dist/src/version-tracking.js

@@ -0,0 +1,200 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { mkdir, readFile, open, rename, realpath, lstat, readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { scope, address, number } from './research.js';
+import { id, text, object, fail, stable } from './model.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); }
+/** A native VT object belongs to an existing research session; it is not another agent session. */
+export class VersionTracking {
+    workspace;
+    research;
+    backend;
+    tasks;
+    constructor(workspace, research, backend, tasks) {
+        this.workspace = workspace;
+        this.research = research;
+        this.backend = backend;
+        this.tasks = tasks;
+    }
+    async ordered(tracking, action) { const key = 'vt:' + tracking, previous = this.tasks.get(key), task = (previous ? previous.catch(() => { }) : Promise.resolve()).then(action); this.tasks.set(key, task); try {
+        return await task;
+    }
+    finally {
+        if (this.tasks.get(key) === task)
+            this.tasks.delete(key);
+    } }
+    async root(tracking) {
+        id(tracking);
+        if (!/^vt_a_[a-zA-Z0-9-]+$/.test(tracking))
+            fail('invalid', 'Invalid Version Tracking object ID.');
+        const root = join(this.workspace.directory, 'version-tracking', tracking);
+        if (await realpath(root) !== resolve(root) || (await lstat(root)).isSymbolicLink())
+            fail('binding', 'VT object left its owned storage.');
+        return root;
+    }
+    async owner(selected, tracking) {
+        const root = await this.root(tracking), owner = object(JSON.parse(await readFile(join(root, 'owner.json'), 'utf8')));
+        if (owner.schema !== 1 || owner.tracking !== tracking || owner.profile !== this.workspace.profile || owner.destination.session !== selected.session || owner.destination.target !== selected.target)
+            fail('binding', 'VT object belongs to another research scope.');
+        await this.workspace.artifacts.verify(owner.sourceSnapshot);
+        await this.workspace.artifacts.verify(owner.destinationSnapshot);
+        return { root, owner };
+    }
+    response(owner, value) {
+        return { ...owner.destination, tracking: owner.tracking, source: { ...owner.source, snapshotSha256: owner.sourceSnapshot.sha256 }, destination: { ...owner.destination, snapshotSha256: owner.destinationSnapshot.sha256 },
+            sourceContextChanged: this.workspace.context(owner.source).generation !== owner.sourceGeneration, destinationContextChanged: this.workspace.context(owner.destination).generation !== owner.destinationGeneration, value };
+    }
+    async native(operation, root, p) { const backend = await this.backend(); if (!backend.sdkFile)
+        fail('configuration', 'Native VT is unavailable.'); return backend.sdkFile('vt.' + operation, { ...p, root }); }
+    async list(selected, offset, limit) {
+        this.workspace.context(selected);
+        const parent = join(this.workspace.directory, 'version-tracking');
+        let entries;
+        try {
+            entries = await readdir(parent, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return { ...selected, items: [], complete: true };
+            throw error;
+        }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        const items = [];
+        let index = offset, visited = 0;
+        for (; index < entries.length && items.length < limit && visited < 1000; index++, visited++) {
+            const entry = entries[index];
+            if (!entry.isDirectory() || !/^vt_a_[a-zA-Z0-9-]+$/.test(entry.name))
+                fail('binding', 'VT inventory contains an unexpected storage entry.');
+            const root = await this.root(entry.name);
+            let owner;
+            try {
+                owner = JSON.parse(await readFile(join(root, 'owner.json'), 'utf8'));
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                fail('binding', 'VT owner record is malformed; retained storage requires inspection.');
+            }
+            if (owner.profile !== this.workspace.profile || owner.destination.session !== selected.session || owner.destination.target !== selected.target)
+                continue;
+            items.push({ tracking: entry.name, source: owner.source, destination: owner.destination, sourceSnapshotSha256: owner.sourceSnapshot.sha256, destinationSnapshotSha256: owner.destinationSnapshot.sha256 });
+        }
+        return { ...selected, items, visited, complete: index === entries.length, ...(index < entries.length ? { nextOffset: index } : {}) };
+    }
+    decisionResult(request, owner, value) {
+        const result = this.response(owner, value);
+        if (object(value).state === 'rejected') {
+            this.workspace.administrationState(request, 'failed', result);
+            fail('rejected', 'Native association constraints rejected this decision; its transaction was rolled back.', result);
+        }
+        this.workspace.administrationState(request, 'applied', result);
+        return result;
+    }
+    async create(selected, source, callerId) {
+        const reserved = this.workspace.reserveAdministration('sdk.vt.create', { ...selected, source }, callerId), tracking = 'vt_' + reserved.request.id;
+        return this.research.paired(selected, source, () => this.ordered(tracking, async () => {
+            const request = this.workspace.administration(reserved.request.id);
+            if (reserved.replay && request.state !== 'accepted') {
+                if (request.state === 'applied')
+                    return request.result;
+                const { root, owner } = await this.owner(selected, tracking);
+                let receipt;
+                try {
+                    receipt = object(JSON.parse(await readFile(join(root, 'created.json'), 'utf8')));
+                }
+                catch {
+                    fail('unknown', 'VT creation is retained without a completed receipt; it is not repeated.');
+                }
+                if (receipt.request !== request.id || receipt.operation !== 'create')
+                    fail('binding', 'VT creation receipt differs.');
+                const result = this.response(owner, receipt.value);
+                this.workspace.administrationState(request.id, 'applied', result);
+                return result;
+            }
+            const backend = await this.backend();
+            await backend.open(selected);
+            await backend.open(source);
+            const sourceSnapshot = await backend.saved(source), destinationSnapshot = await backend.saved(selected), root = join(this.workspace.directory, 'version-tracking', tracking);
+            await mkdir(root, { recursive: true, mode: 0o700 });
+            if (await realpath(root) !== resolve(root))
+                fail('binding', 'VT storage moved.');
+            const owner = { schema: 1, tracking, profile: this.workspace.profile, source, destination: selected, sourceSnapshot, destinationSnapshot,
+                sourceGeneration: this.workspace.context(source).generation, destinationGeneration: this.workspace.context(selected).generation };
+            await persist(join(root, 'owner.json'), owner);
+            this.workspace.administrationState(request.id, 'running', { tracking });
+            try {
+                const value = await this.native('create', root, { request_id: request.id, source_snapshot: await this.workspace.artifacts.verify(sourceSnapshot), destination_snapshot: await this.workspace.artifacts.verify(destinationSnapshot), receipt: join(root, 'created.json') });
+                const result = this.response(owner, value);
+                this.workspace.administrationState(request.id, 'applied', result);
+                return result;
+            }
+            catch (error) {
+                this.workspace.administrationState(request.id, 'unknown', { ...selected, tracking, state: 'unknown' });
+                throw error;
+            }
+        }));
+    }
+    async read(selected, tracking, operation, p) { return this.ordered(tracking, async () => { const { root, owner } = await this.owner(selected, tracking); return this.response(owner, await this.native(operation, root, p)); }); }
+    async decide(selected, tracking, p, callerId) {
+        const reserved = this.workspace.reserveAdministration('sdk.vt.decide', { ...selected, tracking, ...p }, callerId);
+        return this.ordered(tracking, async () => {
+            const request = this.workspace.administration(reserved.request.id), { root, owner } = await this.owner(selected, tracking), receipts = join(root, 'decisions');
+            await mkdir(receipts, { recursive: true, mode: 0o700 });
+            const receiptPath = join(receipts, request.id + '.json');
+            if (reserved.replay && request.state !== 'accepted') {
+                if (request.state === 'applied')
+                    return request.result;
+                if (request.state === 'failed')
+                    fail('rejected', 'The native association decision was rejected and is not repeated.', request.result);
+                let receipt;
+                try {
+                    receipt = object(JSON.parse(await readFile(receiptPath, 'utf8')));
+                }
+                catch {
+                    fail('unknown', 'VT decision is uncertain and is not repeated.');
+                }
+                if (receipt.request !== request.id || receipt.operation !== 'decide')
+                    fail('binding', 'VT decision receipt differs.');
+                return this.decisionResult(request.id, owner, receipt.value);
+            }
+            if (this.workspace.unresolvedSessionAdministration(selected.session, selected.target).some(earlier => earlier.id !== request.id && object(object(earlier.intent).parameters).tracking === tracking))
+                fail('blocked', 'An earlier decision on this VT object is unresolved.');
+            this.workspace.administrationState(request.id, 'running', { ...selected, tracking });
+            try {
+                const value = await this.native('decide', root, { ...p, request_id: request.id, receipt: receiptPath });
+                return this.decisionResult(request.id, owner, value);
+            }
+            catch (error) {
+                if (this.workspace.administration(request.id).state !== 'failed')
+                    this.workspace.administrationState(request.id, 'unknown', { ...selected, tracking, state: 'unknown' });
+                throw error;
+            }
+        });
+    }
+}
+export function trackingCommands(service) {
+    const tracking = { flags: '--tracking <id>', description: 'Native VT object returned by create', required: true }, request = { flags: '--request-id <id>', description: 'Retrieve a retained native decision without repeating it' }, association = [{ flags: '--source-address <address>', description: 'Source address in this VT snapshot', required: true }, { flags: '--destination-address <address>', description: 'Destination address in this VT snapshot', required: true }];
+    return [command('version-tracking', 'Native source/destination match sets, association decisions and markup inventory', [
+            command('list', 'List VT objects owned by this destination research scope, including retained creation stages', ({ options: o }, c) => service(c).list(scope(o), number(o.offset, 1000000), number(o.limit, 1000, 1)), { permission: Permission.ReadOnly, options: [...selectedOptions, { flags: '--limit <count>', description: 'Maximum returned owned VT objects', defaultValue: 100 }, { flags: '--offset <count>', description: 'Inventory offset; use nextOffset after a partial scan', defaultValue: 0 }] }),
+            command('create', 'Correlate immutable source/destination snapshots in a persistent owned native VT project', ({ options: o }, c) => {
+                const selected = scope(o), source = { session: o.sourceSession === undefined ? selected.session : id(o.sourceSession), target: id(o.sourceTarget) };
+                return service(c).create(selected, source, o.requestId === undefined ? undefined : id(o.requestId));
+            }, { permission: Permission.Update, options: [...selectedOptions, { flags: '--source-target <id>', description: 'Source immutable target', required: true }, { flags: '--source-session <id>', description: 'Source research session (default destination session)' }, request] }),
+            command('matches', 'Read native match sets and correlator-specific scores from the saved VT object', ({ options: o }, c) => service(c).read(scope(o), id(o.tracking), 'matches', { limit: number(o.limit, 1000, 1), offset: number(o.offset, 100000) }), { permission: Permission.ReadOnly, options: [...selectedOptions, tracking, { flags: '--limit <count>', description: 'Match page size 1–1000', defaultValue: 100 }, { flags: '--offset <count>', description: 'Page offset', defaultValue: 0 }] }),
+            command('markup', 'Inspect native markup values for one association before agent-directed edits', ({ options: o }, c) => service(c).read(scope(o), id(o.tracking), 'markup', { source_address: address(o.sourceAddress), destination_address: address(o.destinationAddress) }), { permission: Permission.ReadOnly, options: [...selectedOptions, tracking, ...association] }),
+            command('decide', 'Explicitly accept/reject/reset one native association; native one-to-one constraints apply', ({ options: o }, c) => {
+                const decision = text(o.decision);
+                if (!['accepted', 'rejected', 'available'].includes(decision))
+                    fail('invalid', 'Decision must be accepted, rejected or available.');
+                return service(c).decide(scope(o), id(o.tracking), { source_address: address(o.sourceAddress), destination_address: address(o.destinationAddress), decision }, o.requestId === undefined ? undefined : id(o.requestId));
+            }, { permission: Permission.Update, options: [...selectedOptions, tracking, ...association, { flags: '--decision <state>', description: 'accepted, rejected or available', required: true }, request] }),
+        ])];
+}

package/dist/src/workspace.d.ts

@@ -0,0 +1,199 @@
+import { Artifacts, type Artifact } from './artifacts.js';
+export interface ResearchTarget {
+    id: string;
+    name: string;
+    binarySha256: string;
+    size: number;
+    input: Artifact;
+    createdAt: string;
+}
+export interface ResearchSession {
+    id: string;
+    createdAt: string;
+}
+export interface GhidraLoadSettings {
+    autoAnalyze: boolean;
+    language?: string;
+    compilerSpec?: string;
+    imageBase?: string;
+    loader?: string;
+    loaderOptions?: Record<string, string | number | boolean>;
+}
+export interface GhidraModel {
+    target: string;
+    settings: GhidraLoadSettings;
+    state: 'opening' | 'ready' | 'unknown';
+    sharedRevision?: number;
+    sharedSnapshot?: Artifact;
+}
+export interface Scope {
+    session: string;
+    target: string;
+}
+export interface ScalarChange {
+    address: string;
+    field: 'function.name' | 'comment.eol' | 'comment.pre' | 'comment.post' | 'comment.plate' | 'comment.repeatable';
+    original: string | null;
+    local: string | null;
+    /** The field ceased to exist in a retained complex program result. Never a scalar setter. */
+    removed?: true;
+    dependency?: string;
+    conflict?: {
+        shared: string | null;
+    };
+}
+export interface SyncPolicy {
+    publish: 'manual' | 'after-edit' | 'after-save';
+    refresh: 'manual' | 'before-edit';
+}
+export interface GhidraContext extends Scope {
+    /** Internal storage key, never a caller's backend selector. */
+    id: string;
+    tool: 'ghidra';
+    state: 'opening' | 'ready' | 'stopped' | 'needs_recovery';
+    generation: number;
+    baseRevision?: number;
+    baseSnapshot?: Artifact;
+    workingSnapshot?: Artifact;
+    viewEpoch?: number;
+    scalars: ScalarChange[];
+    complexChanges: string[];
+    debugger?: DebuggerState;
+    syncPolicy?: SyncPolicy;
+}
+export interface SavedTrace {
+    id: string;
+    name: string;
+    snapshot: Artifact;
+    snap: string;
+    modules: number;
+    threads: number;
+    connected: boolean;
+    thread?: string;
+}
+export interface DebuggerState {
+    traces: SavedTrace[];
+    active?: string;
+    connected: boolean;
+}
+export type RequestState = 'accepted' | 'running' | 'applied' | 'failed' | 'unknown';
+export interface AdministrationRequest {
+    id: string;
+    operation: string;
+    intent: unknown;
+    state: RequestState;
+    callerId?: string;
+    result?: unknown;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ResearchRequest {
+    id: string;
+    callerId?: string;
+    operation: string;
+    intent: unknown;
+    context: string;
+    state: RequestState;
+    result?: unknown;
+    execution?: unknown;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface Publication extends Scope {
+    id: string;
+    request: string;
+    state: 'preparing' | 'commit_intent' | 'unknown' | 'verified' | 'conflict';
+    expectedRevision: number;
+    snapshot: Artifact;
+    generation: number;
+    scalars: ScalarChange[];
+    complex: boolean;
+    complexChanges?: string[];
+    publishedRevision?: number;
+    detail?: unknown;
+}
+export interface OpenReservation {
+    context: GhidraContext;
+    request: ResearchRequest;
+    replay: boolean;
+}
+type ContextPatch = Partial<Pick<GhidraContext, 'state' | 'baseRevision' | 'baseSnapshot' | 'workingSnapshot' | 'viewEpoch' | 'scalars' | 'complexChanges' | 'debugger' | 'syncPolicy'>>;
+/** Profile root state, deliberately separate from the earlier coordinator.sqlite journals. */
+export declare class Workspace {
+    readonly profile: string;
+    readonly directory: string;
+    readonly artifacts: Artifacts;
+    private readonly db;
+    private namespace;
+    constructor(directory: string, profile: string);
+    close(): void;
+    private transaction;
+    private rememberArtifact;
+    private knownSnapshot;
+    captureSnapshot(path: string): Promise<Artifact>;
+    importTarget(path: string): Promise<ResearchTarget>;
+    target(target: string): ResearchTarget;
+    targets(limit?: number, offset?: number): ResearchTarget[];
+    session(session: string): ResearchSession;
+    sessions(limit?: number, offset?: number): ResearchSession[];
+    model(target: string): GhidraModel;
+    context(scope: Scope): GhidraContext;
+    contexts(session: string, limit?: number, offset?: number): GhidraContext[];
+    private existingRequest;
+    private insertRequest;
+    reserveOpen(target: string, session: string | 'new', settings: GhidraLoadSettings, callerId?: string, mode?: 'headless' | 'gui'): OpenReservation;
+    reserveRequest(scope: Scope, operation: string, parameters: unknown, callerId?: string): {
+        request: ResearchRequest;
+        replay: boolean;
+    };
+    request(request: string): ResearchRequest;
+    reserveAdministration(operation: string, parameters: unknown, callerId?: string): {
+        request: AdministrationRequest;
+        replay: boolean;
+    };
+    administrationByCaller(callerId: string): AdministrationRequest | undefined;
+    requestByCaller(callerId: string): ResearchRequest | undefined;
+    administration(request: string): AdministrationRequest;
+    unresolvedAdministration(): AdministrationRequest[];
+    unresolvedSessionAdministration(session: string, target?: string): AdministrationRequest[];
+    unresolvedServer(): AdministrationRequest[];
+    unresolvedProject(project: string): AdministrationRequest[];
+    administrationState(request: string, state: Exclude<RequestState, 'accepted'>, result?: unknown): AdministrationRequest;
+    unresolved(scope: Scope): ResearchRequest[];
+    startRequest(request: string, execution?: unknown): ResearchRequest;
+    recordRequest(request: string, state: 'applied' | 'failed' | 'unknown', result: unknown): ResearchRequest;
+    private writeRequest;
+    establishModel(target: string, revision: number, snapshot: Artifact): GhidraModel;
+    beginModelInitialization(target: string): GhidraModel;
+    observeShared(target: string, revision: number, snapshot: Artifact): GhidraModel;
+    publication(publication: string): Publication;
+    activePublication(target: string): Publication | undefined;
+    beginPublication(scope: Scope, request: string, expectedRevision: number, snapshot: Artifact): Publication;
+    publicationIntent(publication: string): Publication;
+    unknownPublication(publication: string, detail: unknown): {
+        state: "unknown";
+        detail: unknown;
+        id: string;
+        request: string;
+        expectedRevision: number;
+        snapshot: Artifact;
+        generation: number;
+        scalars: ScalarChange[];
+        complex: boolean;
+        complexChanges?: string[];
+        publishedRevision?: number;
+        session: string;
+        target: string;
+    };
+    finishPublication(publication: string, publishedRevision: number, result: unknown): Publication;
+    rejectPublication(publication: string, result: unknown): Publication;
+    publishedSince(target: string, revision: number): Publication[];
+    saveContext(scope: Scope, expectedGeneration: number, patch: ContextPatch): GhidraContext;
+    /** Snapshot and successful request acknowledgment enter the same durable transaction. */
+    completeSavedRequest(scope: Scope, request: string, expectedGeneration: number, patch: ContextPatch, result: unknown): {
+        context: GhidraContext;
+        request: ResearchRequest;
+    };
+    private writeContext;
+}
+export {};