@eyeauras/insight-cli 0.0.0-stage → 0.1.0

package/dist/src/coordinator.d.ts

@@ -0,0 +1,41 @@
+import { type Batch, type Binding, type FindingRecord, type Snapshot, type Target } from './model.js';
+import { Store } from './store.js';
+/** Ghidra operations are separately acknowledged calls. The journal, not a batch endpoint,
+ * is the recovery boundary. Implementations must preserve staged project directories. */
+export interface Publisher {
+    open(target: Target, batchId: string): Promise<Binding>;
+    checkout(target: Target, binding: Binding): Promise<Snapshot>;
+    read(target: Target, binding: Binding, findings: FindingRecord[]): Promise<Snapshot>;
+    apply(target: Target, binding: Binding, finding: FindingRecord): Promise<void>;
+    save(target: Target, binding: Binding): Promise<void>;
+    checkIn(target: Target, binding: Binding, batchId: string): Promise<number>;
+    published(target: Target, findings: FindingRecord[]): Promise<Snapshot>;
+    history(target: Target, batchId: string): Promise<number[]>;
+    released(target: Target): Promise<boolean>;
+    release(target: Target, binding: Binding): Promise<void>;
+    complete(target: Target, binding: Binding): Promise<void>;
+    /** Return only after every owned publisher process is stopped, staged copy backed up,
+     * and any owned checkout safely released. This must refuse a live/unidentified writer. */
+    abandon(target: Target, batch: Batch): Promise<void>;
+}
+export type Checkpoint = (phase: string, batch: Batch) => Promise<void>;
+export declare class Coordinator {
+    readonly store: Store;
+    readonly publisher: Publisher;
+    private checkpoint;
+    private running;
+    constructor(store: Store, publisher: Publisher, checkpoint?: Checkpoint, running?: Map<string, Promise<Batch | {
+        state: "empty";
+        targetId: string;
+    }>>);
+    settled(): Promise<void>;
+    integrate(targetId: string): Promise<Batch | {
+        state: "empty";
+        targetId: string;
+    }>;
+    private mark;
+    private validate;
+    private integrateOnce;
+    private verify;
+    recover(batchId: string, abandon?: boolean): Promise<Batch>;
+}

package/dist/src/coordinator.js

@@ -0,0 +1,160 @@
+import { assertIdentity, fail, key } from './model.js';
+export class Coordinator {
+    store;
+    publisher;
+    checkpoint;
+    running;
+    constructor(store, publisher, checkpoint = async () => { }, running = new Map()) {
+        this.store = store;
+        this.publisher = publisher;
+        this.checkpoint = checkpoint;
+        this.running = running;
+    }
+    async settled() { await Promise.allSettled([...this.running.values()]); }
+    integrate(targetId) {
+        const active = this.running.get(targetId);
+        if (active)
+            return active;
+        const work = this.integrateOnce(targetId).finally(() => this.running.delete(targetId));
+        this.running.set(targetId, work);
+        return work;
+    }
+    async mark(id, phase, patch = {}) {
+        const batch = this.store.update(id, phase, patch);
+        await this.checkpoint(phase, batch);
+        return batch;
+    }
+    validate(snapshot, target, findings, proposed) {
+        assertIdentity(snapshot.identity, target);
+        if (!Number.isSafeInteger(snapshot.version) || snapshot.version < 1)
+            fail('malformed', 'Readback did not contain a valid version.');
+        for (const finding of findings) {
+            if (!Object.hasOwn(snapshot.values, key(finding)))
+                fail('partial', 'Readback omitted a requested comment.');
+            const actual = snapshot.values[key(finding)];
+            if (actual !== null && typeof actual !== 'string')
+                fail('malformed', 'Readback contained a malformed comment.');
+            if (proposed && actual !== finding.after)
+                fail('verification', 'Published readback differs from the proposal.');
+        }
+    }
+    async integrateOnce(targetId) {
+        const target = this.store.target(targetId);
+        let batch = this.store.begin(targetId);
+        if (!batch)
+            return { state: 'empty', targetId };
+        try {
+            await this.checkpoint('accepted', batch);
+            const binding = await this.publisher.open(target, batch.id);
+            assertIdentity(binding.identity, target);
+            if (binding.role !== 'publisher' || !Number.isSafeInteger(binding.pid) || binding.pid <= 0)
+                fail('binding', 'Publisher binding is invalid.');
+            batch = await this.mark(batch.id, 'applying', { binding });
+            const baseline = await this.publisher.checkout(target, binding);
+            assertIdentity(baseline.identity, target);
+            if (!Number.isSafeInteger(baseline.version) || baseline.version < 1)
+                fail('malformed', 'Checkout did not report its baseline version.');
+            batch = await this.mark(batch.id, 'applying', { baselineVersion: baseline.version, binding });
+            const current = await this.publisher.read(target, binding, batch.findings);
+            this.validate(current, target, batch.findings, false);
+            if (current.version !== baseline.version)
+                fail('binding', 'Local copy is not bound to the fresh checkout baseline.');
+            const scopes = new Map();
+            const conflicts = [];
+            for (const f of batch.findings) {
+                const peer = scopes.get(key(f));
+                if (f.baselineVersion > baseline.version || current.values[key(f)] !== f.before ||
+                    peer && (peer.before !== f.before || peer.after !== f.after)) {
+                    conflicts.push({ findingId: f.findingId, peerFindingId: peer?.findingId, observed: current.values[key(f)], expected: f.before, proposed: f.after });
+                }
+                scopes.set(key(f), f);
+            }
+            if (conflicts.length) {
+                this.store.conflicts(batch.id, conflicts);
+                // No proposal has been applied; release must finish before unblocking the lane.
+                await this.publisher.release(target, binding);
+                batch = await this.mark(batch.id, 'conflict_pending', { detail: { conflicts } });
+                fail('conflict', 'Comment proposals conflict with the current baseline or each other.', batch);
+            }
+            for (const f of scopes.values()) {
+                await this.publisher.apply(target, binding, f);
+                const observed = await this.publisher.read(target, binding, [f]);
+                this.validate(observed, target, [f], true);
+                await this.checkpoint('local_application', this.store.batch(batch.id));
+            }
+            const all = await this.publisher.read(target, binding, batch.findings);
+            this.validate(all, target, batch.findings, true);
+            await this.publisher.save(target, binding);
+            batch = await this.mark(batch.id, 'staged');
+            // Durable check-in intent precedes the remote request. A kill at this boundary is
+            // deliberately uncertain even if the remote call had not started yet.
+            batch = await this.mark(batch.id, 'checking_in');
+            const version = await this.publisher.checkIn(target, binding, batch.id);
+            if (!Number.isSafeInteger(version) || version <= baseline.version)
+                fail('malformed', 'Check-in did not establish a newer server version.');
+            batch = await this.mark(batch.id, 'publication_unknown', { publishedVersion: version });
+            return await this.verify(target, batch);
+        }
+        catch (error) {
+            const latest = this.store.batch(batch.id);
+            if (!['conflict_pending', 'published_verified'].includes(latest.state)) {
+                const uncertain = ['checking_in', 'publication_unknown'].includes(latest.state);
+                const result = this.store.update(batch.id, uncertain ? 'publication_unknown' : 'failed', { detail: { phase: latest.state } });
+                fail(uncertain ? 'unknown' : 'staged', uncertain ? 'Publication outcome is unresolved; reconcile this batch before any retry.' : 'Integration stopped; the journal and staged copy are retained.', result);
+            }
+            throw error;
+        }
+    }
+    async verify(target, batch) {
+        const versions = await this.publisher.history(target, batch.id);
+        if (versions.length !== 1 || versions[0] !== batch.publishedVersion)
+            fail('unknown', 'Server history does not uniquely establish this publication.');
+        const actual = await this.publisher.published(target, batch.findings);
+        this.validate(actual, target, batch.findings, true);
+        if (actual.version !== batch.publishedVersion || !await this.publisher.released(target))
+            fail('unknown', 'Independent readback or checkout release is unresolved.');
+        await this.checkpoint('verification', batch);
+        if (batch.binding)
+            await this.publisher.complete(target, batch.binding);
+        return this.mark(batch.id, 'published_verified');
+    }
+    async recover(batchId, abandon = false) {
+        let batch = this.store.batch(batchId);
+        const target = this.store.target(batch.targetId);
+        if (this.running.has(batch.targetId))
+            fail('busy', 'The publication owner is still executing this lane.');
+        if (['published_verified', 'conflict_pending'].includes(batch.state))
+            return batch;
+        if (batch.ownerPid !== process.pid) {
+            try {
+                process.kill(batch.ownerPid, 0);
+                fail('busy', 'The prior owner is still alive; recovery cannot take over.');
+            }
+            catch (error) {
+                if (error.code !== 'ESRCH')
+                    throw error;
+            }
+        }
+        const intent = this.store.events(batchId).some(e => e.state === 'checking_in');
+        if (intent) {
+            if (abandon)
+                fail('unknown', 'An uncertain check-in cannot be abandoned or retried.');
+            const versions = await this.publisher.history(target, batch.id);
+            if (versions.length !== 1)
+                fail('unknown', 'Server history is insufficient; this lane remains blocked.', batch);
+            batch = this.store.update(batchId, 'publication_unknown', { publishedVersion: versions[0] });
+            try {
+                return await this.verify(target, batch);
+            }
+            catch {
+                fail('unknown', 'Reconciliation could not verify every publication result; this lane remains blocked.', batch);
+            }
+        }
+        if (!abandon)
+            fail('staged', 'A pre-publication stage is retained; use explicit abandon after stopping its publisher.', batch);
+        await this.publisher.abandon(target, batch);
+        // Findings remain observable. A fresh request can explicitly resubmit from a verified
+        // baseline; the original failed batch and stage are never overwritten or replayed.
+        return this.store.update(batchId, 'conflict_pending', { detail: { abandoned: true, requiresNewProposals: true } });
+    }
+}

package/dist/src/cross-results.d.ts

@@ -0,0 +1,14 @@
+import type { Scope } from './workspace.js';
+/** Domain contracts for the pinned comparison leaves, independent of backend acknowledgment. */
+export declare function crossResult(path: string, parameters: Record<string, unknown>, input: unknown): Record<string, unknown>;
+export declare const transferCategories: readonly ["function_names", "function_signatures", "function_plate_comments", "function_calling_conventions", "function_no_return_flags", "function_tags", "function_locals", "data_types", "data_definitions", "data_plate_comments", "instruction_comments", "data_item_comments", "labels", "globals", "external_locations", "bookmarks", "equates"];
+export declare function transferResult(input: unknown, dryRun: boolean): {
+    dryRun: boolean;
+    categories: Record<string, {
+        planned: number;
+        applied: number;
+    }>;
+    total: number;
+};
+/** Routing identities become logical scopes; arbitrary function/symbol names remain untouched. */
+export declare function logicalPrograms(value: unknown, names: Map<string, Scope>): unknown;

package/dist/src/cross-results.js

@@ -0,0 +1,71 @@
+import { object, fail } from './model.js';
+const count = (value) => { if (!Number.isSafeInteger(value) || Number(value) < 0)
+    fail('partial', 'Cross-target result has an invalid count.'); return Number(value); };
+const scores = (value) => { if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1)
+    fail('partial', 'Cross-target result has an invalid similarity score.'); };
+/** Domain contracts for the pinned comparison leaves, independent of backend acknowledgment. */
+export function crossResult(path, parameters, input) {
+    const value = object(input);
+    if (JSON.stringify(value).length > 1048576)
+        fail('limit', 'Cross-target result exceeds one MiB; narrow its scope.');
+    if (path === '/compare_programs_documentation') {
+        if (!Array.isArray(value.programs) || value.programs.length !== 2 || value.count !== 2)
+            fail('partial', 'Comparison did not return both selected contexts.');
+        for (const item of value.programs) {
+            const program = object(item);
+            const total = count(program.total_functions);
+            if (count(program.documented) + count(program.undocumented) !== total)
+                fail('partial', 'Program documentation counts are inconsistent.');
+        }
+    }
+    else if (path === '/diff_functions') {
+        const a = object(value.function_a), b = object(value.function_b);
+        if (typeof a.name !== 'string' || typeof b.name !== 'string')
+            fail('partial', 'Diff omitted its function identities.');
+        scores(object(value.summary).similarity_score);
+        for (const key of ['body_equal', 'body_added', 'body_removed'])
+            count(object(value.summary)[key]);
+        for (const key of ['prologue_diff', 'body_diff', 'epilogue_diff'])
+            if (!Array.isArray(value[key]))
+                fail('partial', 'Diff omitted an instruction section.');
+    }
+    else if (path === '/bulk_fuzzy_match' || path === '/find_similar_functions_fuzzy') {
+        if (!Array.isArray(value.matches) || value.matches.length > Number(parameters.limit ?? (path === '/bulk_fuzzy_match' ? 50 : 20)))
+            fail('partial', 'Matching result exceeds its page.');
+        if (path === '/bulk_fuzzy_match') {
+            count(value.total_source_functions);
+            if (value.offset !== parameters.offset || value.limit !== parameters.limit)
+                fail('partial', 'Matching page changed its selectors.');
+        }
+        else
+            count(value.total_matches);
+    }
+    else
+        fail('schema', 'Cross-target query lacks a result contract.');
+    return value;
+}
+export const transferCategories = ['function_names', 'function_signatures', 'function_plate_comments', 'function_calling_conventions', 'function_no_return_flags',
+    'function_tags', 'function_locals', 'data_types', 'data_definitions', 'data_plate_comments', 'instruction_comments', 'data_item_comments', 'labels', 'globals', 'external_locations', 'bookmarks', 'equates'];
+export function transferResult(input, dryRun) {
+    const value = object(input);
+    if (value.dry_run !== dryRun || count(value.errors) !== 0)
+        fail('partial', 'Documentation transfer reported an incomplete outcome.');
+    const categories = {};
+    let total = 0;
+    for (const key of transferCategories) {
+        const item = object(value[key]), planned = count(item.planned), applied = count(item.applied);
+        if (applied !== planned)
+            fail('partial', 'Documentation transfer skipped part of ' + key);
+        categories[key] = { planned, applied };
+        total += applied;
+    }
+    return { dryRun, categories, total };
+}
+/** Routing identities become logical scopes; arbitrary function/symbol names remain untouched. */
+export function logicalPrograms(value, names) {
+    if (Array.isArray(value))
+        return value.map(item => logicalPrograms(item, names));
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value).filter(([key]) => !['source_path', 'target_path'].includes(key)).map(([key, item]) => [key, ['program', 'source_program', 'target_program'].includes(key) && typeof item === 'string' && names.has(item) ? names.get(item) : logicalPrograms(item, names)]));
+}

package/dist/src/cross.d.ts

@@ -0,0 +1,3 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { Research } from './research.js';
+export declare function crossCommands(research: (context: CommandContext) => Research): CommandDefinition[];

package/dist/src/cross.js

@@ -0,0 +1,43 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { scope } from './research.js';
+import { id, fail } from './model.js';
+import { option, key, parsed, selectedOptions } from './arguments.js';
+import { crossResult } from './cross-results.js';
+import { qualifyQuery } from './query-policy.js';
+const leaves = [
+    { path: '/compare_programs_documentation', group: 'documentation', name: 'compare', params: [] },
+    { path: '/diff_functions', group: 'functions', name: 'diff', params: [{ name: 'address_a', type: 'string', required: true, semantic: 'address' }, { name: 'address_b', type: 'string', required: true, semantic: 'address' }] },
+    { path: '/find_similar_functions_fuzzy', group: 'documentation', name: 'find-similar-functions-fuzzy', params: [{ name: 'function', type: 'string', required: true },
+            { name: 'threshold', type: 'number', required: false, default: '0.7' }, { name: 'limit', type: 'integer', required: false, default: '20' }] },
+    { path: '/bulk_fuzzy_match', group: 'documentation', name: 'bulk-fuzzy-match', params: [{ name: 'threshold', type: 'number', required: false, default: '0.7' },
+            { name: 'offset', type: 'integer', required: false, default: '0' }, { name: 'limit', type: 'integer', required: false, default: '50' }, { name: 'filter', type: 'string', required: false, default: '', allowEmpty: true }] },
+];
+export function crossCommands(research) {
+    const groups = new Map();
+    for (const leaf of leaves) {
+        const children = groups.get(leaf.group) ?? [];
+        groups.set(leaf.group, children);
+        children.push(command(leaf.name, 'Compare two explicitly selected working contexts', async ({ options: o }, c) => {
+            const selected = scope(o), other = { session: o.otherSession === undefined ? selected.session : id(o.otherSession), target: id(o.otherTarget) }, parameters = {};
+            for (const p of leaf.params) {
+                const input = o[key(p.name)];
+                if (input !== undefined)
+                    parameters[p.name] = parsed(p, input);
+            }
+            if (parameters.threshold !== undefined && (Number(parameters.threshold) < 0 || Number(parameters.threshold) > 1))
+                fail('invalid', 'Threshold must be between 0 and 1.');
+            const value = crossResult(leaf.path, parameters, await research(c).crossRead(selected, other, leaf.path, parameters));
+            return { ...selected, other, value: qualifyQuery(leaf.path, value) };
+        }, { permission: Permission.ReadOnly, options: [...selectedOptions, { flags: '--other-target <id>', description: 'Second immutable target', required: true },
+                { flags: '--other-session <id>', description: 'Second context session (defaults to --session)' }, ...leaf.params.map(option)] }));
+    }
+    const documentation = groups.get('documentation');
+    documentation.push(command('transfer', 'Copy documentation into a saved private destination; publish with explicit merge', ({ options: o }, c) => {
+        const selected = scope(o), source = { session: o.sourceSession === undefined ? selected.session : id(o.sourceSession), target: id(o.sourceTarget) };
+        return research(c).transfer(selected, source, Boolean(o.dryRun), o.requestId === undefined ? undefined : id(o.requestId));
+    }, { permission: 'Destructive', options: [...selectedOptions, { flags: '--source-target <id>', description: 'Documentation source target', required: true },
+            { flags: '--source-session <id>', description: 'Source context session (defaults to --session)' },
+            { flags: '--dry-run', description: 'Preview transfer counts without applying documentation' },
+            { flags: '--request-id <id>', description: 'Retrieve the prior transfer outcome after a lost response' }] }));
+    return [...groups].map(([name, children]) => command(name, `${name} across two working contexts`, children));
+}

package/dist/src/data-effects.d.ts

@@ -0,0 +1,3 @@
+import type { ResearchBackend } from './research.js';
+import type { Artifact } from './artifacts.js';
+export declare function verifyDataMutation(backend: ResearchBackend, snapshot: Artifact, path: string, p: Record<string, unknown>, response: Record<string, unknown>): Promise<Record<string, unknown>>;

package/dist/src/data-effects.js

@@ -0,0 +1,103 @@
+import { address } from './research.js';
+import { object, fail } from './model.js';
+const equal = (actual, expected, label) => { if (actual !== expected)
+    fail('partial', `Saved ${label} differs from the requested effect.`); };
+export async function verifyDataMutation(backend, snapshot, path, p, response) {
+    if (!backend.inspect)
+        fail('configuration', 'Data edits require saved-state inspection.');
+    const inspect = (kind, parameters = {}) => backend.inspect(snapshot, { kind, ...parameters });
+    const resolve = async (name) => { const value = await inspect('resolve_type', { name }); equal(value.exists, true, 'type presence'); return object(value.type); };
+    if (path === '/import_data_types') {
+        if (response.parse_succeeded !== true)
+            fail('partial', 'Type import did not complete parsing.');
+        const value = await inspect('import_check', { source: p.source });
+        if (!Array.isArray(value.types) || !value.types.length)
+            fail('partial', 'Imported type inventory is absent.');
+        for (const type of value.types)
+            equal(object(type).matches, true, 'imported type ' + object(type).name);
+        return value;
+    }
+    if (path === '/set_function_this_type') {
+        const value = await inspect('function', { address: p.function_address });
+        equal(value.exists, true, 'member function presence');
+        let name = String(p.this_type).trim();
+        if (!name.endsWith('*'))
+            name += ' *';
+        const pointer = await resolve(name);
+        const parameters = value.parameters;
+        if (!Array.isArray(parameters))
+            fail('partial', 'Saved member parameters are absent.');
+        const self = parameters.find(param => object(param).auto === true && object(param).name === 'this');
+        if (!self)
+            fail('partial', 'Saved implicit this parameter is absent.');
+        equal(object(self).type, pointer.name, 'implicit this type');
+        equal(String(value.namespace).split('::').at(-1), pointer.pointerBase, 'owning class');
+        return value;
+    }
+    if (path === '/clear_flow_and_repair') {
+        if (response.success !== true || response.repair !== true)
+            fail('partial', 'Flow repair lacks a completed outcome.');
+        const range = object(response.seed_range);
+        equal(address(String(range.start_address)), address(p.start_address), 'repair seed start');
+        if (p.end_address)
+            equal(address(String(range.end_address_exclusive)), address(p.end_address), 'repair seed end');
+        const value = await inspect('instruction_range', { address: p.start_address, end_address: range.end_address_exclusive });
+        equal(value.count, object(response.observations).instructions_in_seed_after, 'repaired instruction count');
+        return value;
+    }
+    const data = await inspect('data', { address: p.address });
+    if (path === '/set_global' && p.type_name) {
+        equal(data.exists, true, 'defined global presence');
+        const type = await resolve(p.type_name);
+        if (Number(p.array_length ?? 0) > 0) {
+            const details = object(data.details);
+            equal(details.elementType, type.name, 'global array element');
+            equal(details.elementCount, p.array_length, 'global array length');
+        }
+        else
+            equal(data.type, type.name, 'global type');
+    }
+    if (path === '/apply_data_classification') {
+        equal(data.exists, true, 'classified data presence');
+        const definition = object(p.type_definition);
+        if (p.classification === 'PRIMITIVE') {
+            const type = await resolve(definition.type);
+            equal(data.type, type.name, 'classified primitive type');
+        }
+        if (p.classification === 'STRUCTURE') {
+            equal(data.type, definition.name, 'classified structure type');
+            const type = await resolve(definition.name);
+            const fields = type.fields;
+            if (!Array.isArray(fields) || !Array.isArray(definition.fields))
+                fail('partial', 'Classified structure layout is absent.');
+            equal(fields.length, definition.fields.length, 'classified field count');
+            for (let i = 0; i < fields.length; i++) {
+                const requested = object(definition.fields[i]), expected = await resolve(requested.type);
+                equal(object(fields[i]).name, requested.name, 'classified field name');
+                equal(object(fields[i]).type, expected.name, 'classified field type');
+            }
+        }
+        if (p.classification === 'ARRAY') {
+            const type = await resolve(definition.element_type ?? definition.element_struct), details = object(data.details);
+            equal(details.elementType, type.name, 'classified array element');
+            equal(details.elementCount, Number(definition.count), 'classified array length');
+        }
+        if (p.classification === 'STRING')
+            equal(data.isString, true, 'classified string value');
+        if (p.comment) {
+            const comment = await inspect('comments', { address: p.address });
+            equal(comment.pre, String(p.comment).replaceAll('\\n', '\n').replaceAll('\\t', '\t').replaceAll('\\r', '\r'), 'classified comment');
+        }
+    }
+    let symbols, comments;
+    if (p.name) {
+        symbols = await inspect('symbols', { address: p.address });
+        if (!Array.isArray(symbols.symbols) || !symbols.symbols.some(symbol => object(symbol).name === p.name))
+            fail('partial', 'Saved global label is absent.');
+    }
+    if (path === '/set_global' && p.plate_comment) {
+        comments = await inspect('comments', { address: p.address });
+        equal(comments.plate, p.plate_comment, 'global plate comment');
+    }
+    return { data, ...(symbols ? { symbols } : {}), ...(comments ? { comments } : {}) };
+}

package/dist/src/debugger-results.d.ts

@@ -0,0 +1,4 @@
+import type { ResearchBackend } from './research.js';
+import type { Artifact } from './artifacts.js';
+export declare function debuggerProgramMetadata(backend: Pick<ResearchBackend, 'inspect'>, snapshot: Artifact): Promise<string | undefined>;
+export declare function debuggerResult(operation: string, p: Record<string, unknown>, raw: unknown): Record<string, unknown> | Record<string, unknown>[];

package/dist/src/debugger-results.js

@@ -0,0 +1,151 @@
+import { object, fail, text } from './model.js';
+import { address, publicAddress } from './research.js';
+const array = (raw) => { if (!Array.isArray(raw))
+    fail('partial', 'Debugger inventory is absent.'); return raw.map(object); };
+const count = (value) => { if (!Number.isSafeInteger(value) || Number(value) < 0)
+    fail('partial', 'Debugger count is invalid.'); };
+export async function debuggerProgramMetadata(backend, snapshot) {
+    if (!backend.inspect)
+        return undefined;
+    const value = object(await backend.inspect(snapshot, { kind: 'debugger_bookmarks' }));
+    if (typeof value.fingerprint !== 'string' || !/^[a-f0-9]{64}$/.test(value.fingerprint))
+        fail('partial', 'Debugger program metadata inspection is incomplete.');
+    count(value.count);
+    return value.fingerprint;
+}
+export function debuggerResult(operation, p, raw) {
+    if (['launch_offers', 'traces', 'modules', 'list_breakpoints', 'stack_trace'].includes(operation)) {
+        const rows = array(raw);
+        for (const row of rows) {
+            if (operation === 'launch_offers') {
+                text(row.title);
+                text(row.config_name);
+                if (typeof row.supports_image !== 'boolean' || typeof row.requires_image !== 'boolean' || !Array.isArray(row.parameters))
+                    fail('partial', 'Debugger launch offer is incomplete.');
+            }
+            if (operation === 'traces') {
+                text(row.name);
+                if (typeof row.current !== 'boolean')
+                    fail('partial', 'Trace selection is absent.');
+                count(row.module_count);
+                count(row.thread_count);
+            }
+            if (operation === 'modules') {
+                text(row.name);
+                if (row.base !== undefined)
+                    row.base = publicAddress(row.base);
+                if (row.size !== undefined && !/^0x[0-9a-f]+$/i.test(String(row.size)))
+                    fail('partial', 'Module size is invalid.');
+            }
+            if (operation === 'list_breakpoints') {
+                row.address = publicAddress(row.address);
+                count(row.trace_location_count);
+                if (typeof row.name !== 'string' || row.name.length > 4096 || row.name.includes('\0'))
+                    fail('partial', 'Breakpoint name is invalid.');
+                text(row.state);
+                if (!Array.isArray(row.kinds) || row.kinds.some(kind => typeof kind !== 'string'))
+                    fail('partial', 'Breakpoint kinds are absent.');
+            }
+            if (operation === 'stack_trace') {
+                count(row.level);
+                if (row.address !== undefined)
+                    row.address = publicAddress(row.address);
+            }
+        }
+        return rows;
+    }
+    const value = object(raw);
+    if (['write_memory', 'write_register'].includes(operation)) {
+        if (value.status !== 'written' || value.verified_from !== 'live_target_refresh' || !/^-?\d+$/.test(String(value.snap)))
+            fail('partial', 'Live write omitted independent refreshed target verification.');
+        if (operation === 'write_memory') {
+            if (address(value.address) !== address(p.address) || String(value.bytes_hex).toLowerCase() !== String(p.bytes_hex).toLowerCase() || Number(value.size) !== String(p.bytes_hex).length / 2)
+                fail('partial', 'Live memory verification differs from the requested bytes.');
+            value.address = publicAddress(value.address);
+        }
+        else if (String(value.register).toLowerCase() !== String(p.register).toLowerCase() || !/^(?:0x)?[a-f0-9]+$/i.test(String(value.value)) || BigInt('0x' + String(value.value).replace(/^0x/i, '')) !== BigInt('0x' + String(p.value).replace(/^0x/i, '')) || !Number.isSafeInteger(value.bits) || Number(value.bits) < 1 || Number(value.bits) > 512)
+            fail('partial', 'Live register verification differs from the requested value.');
+    }
+    else if (['timeline', 'objects', 'object_values'].includes(operation)) {
+        if (!Array.isArray(value.items) || typeof value.complete !== 'boolean' || value.items.length > Number(p.limit ?? 1000))
+            fail('partial', 'Trace inventory omitted its bounded completion contract.');
+        for (const rawRow of value.items) {
+            const row = object(rawRow);
+            if (operation === 'timeline') {
+                if (!/^-?\d+$/.test(String(row.snap)) || typeof row.description !== 'string')
+                    fail('partial', 'Trace timeline row is incomplete.');
+            }
+            if (operation === 'objects') {
+                if (!/^\d+$/.test(String(row.object_id)) || typeof row.path !== 'string' || typeof row.schema !== 'string' || typeof row.life !== 'string')
+                    fail('partial', 'Trace object row is incomplete.');
+            }
+            if (operation === 'object_values') {
+                if (row.key !== p.key || typeof row.lifespan !== 'string' || typeof object(row.value).kind !== 'string')
+                    fail('partial', 'Trace value row differs from the selected key.');
+            }
+        }
+        if (operation === 'objects' && (!Number.isSafeInteger(value.visited) || Number(value.visited) < 0 || Number(value.visited) > Number(p.max_scan)))
+            fail('partial', 'Trace object work budget is inconsistent.');
+        if (operation === 'object_values' && String(value.object_id) !== String(p.object_id))
+            fail('binding', 'Trace value query selected another object.');
+    }
+    else if (operation === 'schedule') {
+        if (value.validated !== true || value.executed !== false || typeof value.schedule !== 'string' || !/^-?\d+$/.test(String(value.base_snap)) || !/^\d+$/.test(String(value.ticks)) || !/^\d+$/.test(String(value.patches)) || typeof value.snap_only !== 'boolean')
+            fail('partial', 'Trace schedule validation is incomplete.');
+    }
+    else if (operation === 'status') {
+        if (value.debugger_active !== true || typeof value.trace_active !== 'boolean')
+            fail('partial', 'Debugger status is incomplete.');
+        count(value.open_traces);
+        if (value.trace_active) {
+            if (typeof value.target_connected !== 'boolean')
+                fail('partial', 'Trace connection state is absent.');
+            count(value.module_count);
+            if (value.execution_state !== undefined && !['RUNNING', 'STOPPED', 'ALIVE', 'TERMINATED', 'UNKNOWN', 'INACTIVE'].includes(String(value.execution_state)))
+                fail('partial', 'Debugger execution state is invalid.');
+        }
+    }
+    else if (operation === 'registers') {
+        for (const [name, register] of Object.entries(value)) {
+            text(name, 128);
+            if (typeof register !== 'string' || !/^0x[a-f0-9]{1,16}$/i.test(register))
+                fail('partial', 'Register result is not an exact hexadecimal value.');
+        }
+    }
+    else if (operation === 'read_memory') {
+        if (address(value.address) !== address(p.address) || !Number.isSafeInteger(value.size) || Number(value.size) < 0 || Number(value.size) > Number(p.size) || typeof value.hex !== 'string' || !/^(?:[a-f0-9]{2})*$/i.test(value.hex) || value.hex.length !== Number(value.size) * 2 || !Array.isArray(value.dwords) || value.dwords.length !== Math.floor(Number(value.size) / 4))
+            fail('partial', 'Debugger memory read is inconsistent.');
+        value.address = publicAddress(value.address);
+        for (let i = 0; i < value.dwords.length; i++) {
+            const bytes = value.hex.slice(i * 8, i * 8 + 8).match(/../g).reverse().join('');
+            if (typeof value.dwords[i] !== 'string' || String(value.dwords[i]).toLowerCase() !== '0x' + bytes.toLowerCase())
+                fail('partial', 'Debugger DWORDs differ from its memory bytes.');
+        }
+    }
+    else if (operation === 'static_to_dynamic') {
+        if (address(value.static_address) !== address(p.address))
+            fail('binding', 'Static mapping selected another address.');
+        value.static_address = publicAddress(value.static_address);
+        value.dynamic_address = publicAddress(value.dynamic_address);
+    }
+    else if (operation === 'dynamic_to_static') {
+        if (address(value.dynamic_address) !== address(p.address) || typeof value.module !== 'string' || !/^0x[0-9a-f]+$/i.test(String(value.offset)))
+            fail('partial', 'Dynamic mapping result is incomplete.');
+        value.dynamic_address = publicAddress(value.dynamic_address);
+    }
+    else {
+        const expected = { launch: 'launched', resume: 'resumed', interrupt: 'interrupted', step: p.kind === 'out' ? 'stepped_out' : 'stepped', set_breakpoint: 'set', remove_breakpoint: 'removed' };
+        if (value.status !== expected[operation] || !expected[operation])
+            fail('partial', 'Debugger action did not establish its expected result.');
+        if (operation === 'launch') {
+            text(value.offer_title);
+            text(value.trace_name);
+        }
+        if (operation === 'set_breakpoint' || operation === 'remove_breakpoint') {
+            if (address(value.address) !== address(p.address))
+                fail('binding', 'Breakpoint action selected another address.');
+            value.address = publicAddress(value.address);
+        }
+    }
+    return value;
+}

package/dist/src/debugger-supervisor.d.ts

@@ -0,0 +1 @@
+export {};