@eyeauras/insight-cli 0.0.0-stage → 0.2.0

package/dist/src/workspace.js

@@ -0,0 +1,564 @@
+import { DatabaseSync } from 'node:sqlite';
+import { chmodSync, mkdirSync, realpathSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { Artifacts } from './artifacts.js';
+import { digest, fail, id, stable, text, version } from './model.js';
+const now = () => new Date().toISOString();
+function loadSettings(value) {
+    if (typeof value.autoAnalyze !== 'boolean' || Object.keys(value).some(key => !['autoAnalyze', 'language', 'compilerSpec', 'imageBase', 'loader', 'loaderOptions'].includes(key)))
+        fail('invalid', 'Ghidra load settings are malformed.');
+    const result = { autoAnalyze: value.autoAnalyze };
+    if (value.language !== undefined)
+        result.language = text(value.language, 128);
+    if (value.compilerSpec !== undefined)
+        result.compilerSpec = text(value.compilerSpec, 128);
+    if (value.loader !== undefined)
+        result.loader = text(value.loader, 512);
+    if (value.loaderOptions !== undefined) {
+        if (!value.loader || !value.loaderOptions || Array.isArray(value.loaderOptions) || typeof value.loaderOptions !== 'object' || Object.keys(value.loaderOptions).length > 64)
+            fail('invalid', 'Loader options require an explicit loader and at most 64 named primitive values.');
+        const options = {};
+        for (const [key, item] of Object.entries(value.loaderOptions)) {
+            text(key, 512);
+            if (!['string', 'number', 'boolean'].includes(typeof item) || typeof item === 'number' && !Number.isSafeInteger(item))
+                fail('invalid', 'Loader options require exact primitive values.');
+            if (typeof item === 'string' && (item.length > 4096 || /[\u0000-\u0008\u000b\u000c\u000e-\u001f]/.test(item)))
+                fail('invalid', 'Loader option text exceeds its bound.');
+            options[key] = item;
+        }
+        result.loaderOptions = options;
+    }
+    if (value.imageBase !== undefined) {
+        const address = text(value.imageBase, 128).toLowerCase().replace(/^0x/, '');
+        if (!/^[a-f0-9]+$/.test(address))
+            fail('invalid', 'Image base must be hexadecimal.');
+        result.imageBase = address.replace(/^0+(?=.)/, '');
+    }
+    return result;
+}
+function bounded(value) {
+    const result = stable(value);
+    if (typeof result !== 'string' || Buffer.byteLength(result) > 1024 * 1024)
+        fail('limit', 'Durable request or context exceeds 1 MiB.');
+    return result;
+}
+function page(limit, offset) {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100 || !Number.isSafeInteger(offset) || offset < 0)
+        fail('invalid', 'Pagination requires a limit of 1–100 and a nonnegative offset.');
+}
+/** Profile root state, deliberately separate from the earlier coordinator.sqlite journals. */
+export class Workspace {
+    profile;
+    directory;
+    artifacts;
+    db;
+    namespace;
+    constructor(directory, profile) {
+        this.profile = profile;
+        text(profile);
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        this.directory = realpathSync.native(directory);
+        this.artifacts = new Artifacts(this.directory);
+        const path = join(this.directory, 'workspace.sqlite');
+        this.db = new DatabaseSync(path);
+        chmodSync(path, 0o600);
+        try {
+            if (this.db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='metadata'").get()) {
+                const binding = this.db.prepare('SELECT value FROM metadata WHERE key=?').get('profile');
+                if (binding && binding.value !== profile)
+                    fail('binding', 'Workspace belongs to a different profile; restore its original profile.');
+            }
+            if (Number(this.db.prepare('PRAGMA user_version').get()?.user_version) > 5)
+                fail('binding', 'Workspace schema is newer than this build; preserve it and use the matching build.');
+            this.db.exec(`PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; PRAGMA foreign_keys=ON;
+        CREATE TABLE IF NOT EXISTS metadata(key TEXT PRIMARY KEY, value TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS artifacts(id TEXT PRIMARY KEY, data TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS targets(id TEXT PRIMARY KEY, sha TEXT NOT NULL UNIQUE, data TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS sessions(id TEXT PRIMARY KEY, data TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS ghidra_models(target TEXT PRIMARY KEY REFERENCES targets(id), data TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS contexts(id TEXT PRIMARY KEY, session TEXT NOT NULL REFERENCES sessions(id),
+          target TEXT NOT NULL REFERENCES ghidra_models(target), generation INTEGER NOT NULL, data TEXT NOT NULL,
+          UNIQUE(session,target));
+        CREATE TABLE IF NOT EXISTS requests(id TEXT PRIMARY KEY, caller_id TEXT UNIQUE, hash TEXT NOT NULL,
+          context TEXT NOT NULL REFERENCES contexts(id), state TEXT NOT NULL, data TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS publications(id TEXT PRIMARY KEY, target TEXT NOT NULL REFERENCES ghidra_models(target), state TEXT NOT NULL, data TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS administration_requests(id TEXT PRIMARY KEY,caller_id TEXT UNIQUE,hash TEXT NOT NULL,state TEXT NOT NULL,data TEXT NOT NULL);
+        CREATE UNIQUE INDEX IF NOT EXISTS active_publication ON publications(target) WHERE state IN ('preparing','commit_intent','unknown');
+        PRAGMA user_version=5;`);
+            this.transaction(() => {
+                const binding = this.db.prepare('SELECT value FROM metadata WHERE key=?').get('profile');
+                if (binding && binding.value !== profile)
+                    fail('binding', 'Workspace belongs to a different profile; restore its original profile.');
+                if (!binding) {
+                    this.db.prepare('INSERT INTO metadata VALUES(?,?)').run('profile', profile);
+                    this.db.prepare('INSERT INTO metadata VALUES(?,?)').run('namespace', randomUUID());
+                }
+                this.namespace = String(this.db.prepare('SELECT value FROM metadata WHERE key=?').get('namespace').value);
+            });
+        }
+        catch (error) {
+            this.db.close();
+            throw error;
+        }
+    }
+    close() { this.db.close(); }
+    transaction(action) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const result = action();
+            this.db.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    rememberArtifact(artifact) {
+        this.artifacts.path(artifact);
+        const row = this.db.prepare('SELECT data FROM artifacts WHERE id=?').get(artifact.id);
+        if (row && row.data !== stable(artifact))
+            fail('artifact', 'Artifact identity has inconsistent metadata.');
+        this.db.prepare('INSERT OR IGNORE INTO artifacts VALUES(?,?)').run(artifact.id, stable(artifact));
+    }
+    knownSnapshot(artifact) {
+        this.artifacts.path(artifact);
+        if (artifact.kind !== 'snapshot' || this.db.prepare('SELECT data FROM artifacts WHERE id=?').get(artifact.id)?.data !== stable(artifact))
+            fail('artifact', 'Context requires a captured immutable snapshot.');
+    }
+    async captureSnapshot(path) {
+        const artifact = await this.artifacts.capture(path, 'snapshot');
+        this.rememberArtifact(artifact);
+        return artifact;
+    }
+    async importTarget(path) {
+        const name = text(basename(path), 512);
+        const input = await this.artifacts.capture(path, 'input');
+        return this.transaction(() => {
+            this.rememberArtifact(input);
+            const row = this.db.prepare('SELECT id FROM targets WHERE sha=?').get(input.sha256);
+            if (row)
+                return this.target(String(row.id));
+            const target = {
+                id: 't_' + digest([this.namespace, input.sha256]).slice(0, 32), name,
+                binarySha256: input.sha256, size: input.size, input, createdAt: now(),
+            };
+            this.db.prepare('INSERT INTO targets VALUES(?,?,?)').run(target.id, input.sha256, stable(target));
+            return target;
+        });
+    }
+    target(target) {
+        const row = this.db.prepare('SELECT data FROM targets WHERE id=?').get(id(target));
+        if (!row)
+            fail('notFound', 'Target was not found in the selected profile.');
+        return JSON.parse(String(row.data));
+    }
+    targets(limit = 100, offset = 0) {
+        page(limit, offset);
+        return this.db.prepare('SELECT data FROM targets ORDER BY rowid LIMIT ? OFFSET ?').all(limit, offset).map(row => JSON.parse(String(row.data)));
+    }
+    session(session) {
+        const row = this.db.prepare('SELECT data FROM sessions WHERE id=?').get(id(session));
+        if (!row)
+            fail('notFound', 'Session was not found in the selected profile.');
+        return JSON.parse(String(row.data));
+    }
+    sessions(limit = 100, offset = 0) {
+        page(limit, offset);
+        return this.db.prepare('SELECT data FROM sessions ORDER BY rowid LIMIT ? OFFSET ?').all(limit, offset).map(row => JSON.parse(String(row.data)));
+    }
+    model(target) {
+        this.target(target);
+        const row = this.db.prepare('SELECT data FROM ghidra_models WHERE target=?').get(target);
+        if (!row)
+            fail('notFound', 'Target has no Ghidra model.');
+        return JSON.parse(String(row.data));
+    }
+    context(scope) {
+        this.session(scope.session);
+        this.target(scope.target);
+        const row = this.db.prepare('SELECT data FROM contexts WHERE session=? AND target=?').get(scope.session, scope.target);
+        if (!row)
+            fail('notFound', 'No Ghidra context exists for this session and target; open it first.');
+        return JSON.parse(String(row.data));
+    }
+    contexts(session, limit = 100, offset = 0) {
+        this.session(session);
+        page(limit, offset);
+        return this.db.prepare('SELECT data FROM contexts WHERE session=? ORDER BY rowid LIMIT ? OFFSET ?').all(session, limit, offset).map(row => JSON.parse(String(row.data)));
+    }
+    existingRequest(callerId, intentHash) {
+        if (callerId === undefined)
+            return;
+        if (this.db.prepare('SELECT id FROM administration_requests WHERE caller_id=?').get(id(callerId)))
+            fail('idempotency', 'Request ID already identifies a profile administration operation.');
+        const row = this.db.prepare('SELECT id,hash FROM requests WHERE caller_id=?').get(id(callerId));
+        if (!row)
+            return;
+        if (row.hash !== intentHash)
+            fail('idempotency', 'Request ID was already used with different effective input.');
+        return this.request(String(row.id));
+    }
+    insertRequest(context, operation, intent, callerId, hash) {
+        const request = { id: 'q_' + randomUUID(), operation: text(operation, 128), intent,
+            context, state: 'accepted', ...(callerId === undefined ? {} : { callerId: id(callerId) }), createdAt: now(), updatedAt: now() };
+        this.db.prepare('INSERT INTO requests VALUES(?,?,?,?,?,?)').run(request.id, callerId ?? null, hash, context, request.state, bounded(request));
+        return request;
+    }
+    reserveOpen(target, session, settings, callerId, mode) {
+        this.target(target);
+        const normalized = loadSettings(settings);
+        if (session !== 'new')
+            this.session(session);
+        if (mode !== undefined && !['headless', 'gui'].includes(mode))
+            fail('invalid', 'Requested tool mode is invalid.');
+        const intent = { operation: 'ghidra.open', target, session, settings: normalized, ...(mode ? { mode } : {}) };
+        const hash = digest(intent);
+        return this.transaction(() => {
+            const previous = this.existingRequest(callerId, hash);
+            if (previous) {
+                const row = this.db.prepare('SELECT data FROM contexts WHERE id=?').get(previous.context);
+                return { context: JSON.parse(String(row.data)), request: previous, replay: true };
+            }
+            const row = this.db.prepare('SELECT data FROM ghidra_models WHERE target=?').get(target);
+            if (row) {
+                if (stable(JSON.parse(String(row.data)).settings) !== stable(normalized))
+                    fail('binding', 'Target already uses different Ghidra load settings.');
+            }
+            else {
+                const model = { target, settings: normalized, state: 'opening' };
+                this.db.prepare('INSERT INTO ghidra_models VALUES(?,?)').run(target, stable(model));
+            }
+            if (session === 'new') {
+                const selected = { id: 's_' + randomUUID(), createdAt: now() };
+                this.db.prepare('INSERT INTO sessions VALUES(?,?)').run(selected.id, stable(selected));
+                session = selected.id;
+            }
+            const existing = this.db.prepare('SELECT data FROM contexts WHERE session=? AND target=?').get(session, target);
+            const context = existing ? JSON.parse(String(existing.data)) : {
+                id: 'c_' + randomUUID(), session, target, tool: 'ghidra', state: 'opening', generation: 0, scalars: [], complexChanges: [],
+            };
+            if (!existing)
+                this.db.prepare('INSERT INTO contexts VALUES(?,?,?,?,?)').run(context.id, session, target, 0, stable(context));
+            return { context, request: this.insertRequest(context.id, 'ghidra.open', intent, callerId, hash), replay: false };
+        });
+    }
+    reserveRequest(scope, operation, parameters, callerId) {
+        const context = this.context(scope);
+        const intent = { operation: text(operation, 128), session: scope.session, target: scope.target, parameters };
+        bounded(intent);
+        const hash = digest(intent);
+        return this.transaction(() => {
+            const previous = this.existingRequest(callerId, hash);
+            return previous ? { request: previous, replay: true } : { request: this.insertRequest(context.id, operation, intent, callerId, hash), replay: false };
+        });
+    }
+    request(request) {
+        const row = this.db.prepare('SELECT data FROM requests WHERE id=?').get(id(request));
+        if (!row)
+            fail('notFound', 'Request was not found in the selected profile.');
+        return JSON.parse(String(row.data));
+    }
+    reserveAdministration(operation, parameters, callerId) {
+        const intent = { operation: text(operation, 128), parameters }, hash = digest(intent);
+        bounded(intent);
+        return this.transaction(() => {
+            if (callerId !== undefined) {
+                id(callerId);
+                if (this.db.prepare('SELECT id FROM requests WHERE caller_id=?').get(callerId))
+                    fail('idempotency', 'Request ID already identifies scoped research.');
+                const row = this.db.prepare('SELECT id,hash FROM administration_requests WHERE caller_id=?').get(callerId);
+                if (row) {
+                    if (row.hash !== hash)
+                        fail('idempotency', 'Request ID was already used with different effective input.');
+                    return { request: this.administration(String(row.id)), replay: true };
+                }
+            }
+            const request = { id: 'a_' + randomUUID(), operation, intent, state: 'accepted', ...(callerId ? { callerId } : {}), createdAt: now(), updatedAt: now() };
+            this.db.prepare('INSERT INTO administration_requests VALUES(?,?,?,?,?)').run(request.id, callerId ?? null, hash, request.state, bounded(request));
+            return { request, replay: false };
+        });
+    }
+    administrationByCaller(callerId) { const row = this.db.prepare('SELECT id FROM administration_requests WHERE caller_id=?').get(id(callerId)); return row ? this.administration(String(row.id)) : undefined; }
+    requestByCaller(callerId) { const row = this.db.prepare('SELECT id FROM requests WHERE caller_id=?').get(id(callerId)); return row ? this.request(String(row.id)) : undefined; }
+    administration(request) {
+        const row = this.db.prepare('SELECT data FROM administration_requests WHERE id=?').get(id(request));
+        if (!row)
+            fail('notFound', 'Administration request was not found in this profile.');
+        return JSON.parse(String(row.data));
+    }
+    unresolvedAdministration() {
+        return this.db.prepare("SELECT data FROM administration_requests WHERE state IN ('running','unknown') ORDER BY rowid LIMIT 100")
+            .all().map(row => JSON.parse(String(row.data)));
+    }
+    unresolvedSessionAdministration(session, target) {
+        this.session(session);
+        if (target)
+            this.target(target);
+        return this.db.prepare("SELECT data FROM administration_requests WHERE state IN ('running','unknown') AND json_extract(data,'$.intent.parameters.session')=? AND (? IS NULL OR json_extract(data,'$.intent.parameters.target') IS NULL OR json_extract(data,'$.intent.parameters.target')=?) ORDER BY rowid LIMIT 100")
+            .all(session, target ?? null, target ?? null).map(row => JSON.parse(String(row.data)));
+    }
+    unresolvedServer() {
+        return this.db.prepare("SELECT data FROM administration_requests WHERE state IN ('running','unknown') AND json_extract(data,'$.operation') LIKE 'server.%' ORDER BY rowid LIMIT 100")
+            .all().map(row => JSON.parse(String(row.data)));
+    }
+    unresolvedProject(project) {
+        return this.db.prepare("SELECT data FROM administration_requests WHERE state IN ('running','unknown') AND json_extract(data,'$.intent.parameters.project')=? ORDER BY rowid LIMIT 100")
+            .all(project).map(row => JSON.parse(String(row.data)));
+    }
+    administrationState(request, state, result) {
+        return this.transaction(() => {
+            const previous = this.administration(request);
+            if (previous.state === 'applied' || previous.state === 'failed') {
+                if (previous.state !== state || stable(previous.result) !== stable(result))
+                    fail('idempotency', 'A completed administration outcome is immutable.');
+                return previous;
+            }
+            if (state === 'running' && previous.state !== 'accepted')
+                fail('blocked', 'Administration operation already started; do not replay it.');
+            const next = { ...previous, state, ...(result === undefined ? {} : { result }), updatedAt: now() };
+            this.db.prepare('UPDATE administration_requests SET state=?,data=? WHERE id=?').run(state, bounded(next), request);
+            return next;
+        });
+    }
+    unresolved(scope) {
+        const context = this.context(scope);
+        return this.db.prepare("SELECT data FROM requests WHERE context=? AND state IN ('running','unknown') ORDER BY rowid LIMIT 100")
+            .all(context.id).map(row => JSON.parse(String(row.data)));
+    }
+    startRequest(request, execution) {
+        return this.transaction(() => {
+            const previous = this.request(request);
+            if (previous.state !== 'accepted')
+                fail('blocked', 'Request already started; reconcile its recorded outcome before continuing.');
+            const next = { ...previous, state: 'running', ...(execution === undefined ? {} : { execution }), updatedAt: now() };
+            this.db.prepare('UPDATE requests SET state=?,data=? WHERE id=?').run(next.state, bounded(next), next.id);
+            return next;
+        });
+    }
+    recordRequest(request, state, result) {
+        return this.transaction(() => this.writeRequest(request, state, result));
+    }
+    writeRequest(request, state, result) {
+        const previous = this.request(request);
+        if (previous.state === 'applied' || previous.state === 'failed') {
+            if (state !== previous.state || stable(result) !== stable(previous.result))
+                fail('idempotency', 'A completed request outcome is immutable.');
+            return previous;
+        }
+        if (state === 'applied' && previous.state === 'accepted')
+            fail('binding', 'Request must start before an effect can be acknowledged.');
+        const next = { ...previous, state, result, updatedAt: now() };
+        this.db.prepare('UPDATE requests SET state=?,data=? WHERE id=?').run(next.state, bounded(next), next.id);
+        return next;
+    }
+    establishModel(target, revision, snapshot) {
+        version(revision);
+        this.knownSnapshot(snapshot);
+        return this.transaction(() => {
+            const model = this.model(target);
+            if (model.state === 'ready')
+                fail('binding', 'Ghidra model was already initialized; publication must verify its shared base.');
+            const next = { ...model, state: 'ready', sharedRevision: revision, sharedSnapshot: snapshot };
+            this.db.prepare('UPDATE ghidra_models SET data=? WHERE target=?').run(stable(next), target);
+            return next;
+        });
+    }
+    beginModelInitialization(target) {
+        return this.transaction(() => {
+            const model = this.model(target);
+            if (model.state !== 'opening')
+                fail('blocked', 'Shared model setup already started; reconcile its persisted outcome.');
+            const next = { ...model, state: 'unknown' };
+            this.db.prepare('UPDATE ghidra_models SET data=? WHERE target=?').run(stable(next), target);
+            return next;
+        });
+    }
+    observeShared(target, revision, snapshot) {
+        version(revision);
+        this.knownSnapshot(snapshot);
+        return this.transaction(() => {
+            const model = this.model(target);
+            if (model.state !== 'ready')
+                fail('blocked', 'Shared model outcome requires reconciliation before accepting another baseline.');
+            if (revision < (model.sharedRevision ?? 1))
+                fail('binding', 'Shared version history regressed.');
+            const next = { ...model, sharedRevision: revision, sharedSnapshot: snapshot };
+            this.db.prepare('UPDATE ghidra_models SET data=? WHERE target=?').run(stable(next), target);
+            return next;
+        });
+    }
+    publication(publication) {
+        const row = this.db.prepare('SELECT data FROM publications WHERE id=?').get(id(publication));
+        if (!row)
+            fail('notFound', 'Publication was not found in this profile.');
+        return JSON.parse(String(row.data));
+    }
+    activePublication(target) {
+        this.target(target);
+        const row = this.db.prepare("SELECT data FROM publications WHERE target=? AND state IN ('preparing','commit_intent','unknown')").get(target);
+        return row ? JSON.parse(String(row.data)) : undefined;
+    }
+    beginPublication(scope, request, expectedRevision, snapshot) {
+        version(expectedRevision);
+        this.knownSnapshot(snapshot);
+        return this.transaction(() => {
+            const context = this.context(scope), intent = this.request(request), model = this.model(scope.target);
+            if (intent.context !== context.id || intent.state !== 'running')
+                fail('binding', 'Publication does not match its running context request.');
+            const active = this.activePublication(scope.target);
+            if (active || model.state !== 'ready')
+                fail('blocked', 'Shared model has an unresolved publication; reconcile it before another merge.');
+            const publication = { ...scope, id: request, request, state: 'preparing', expectedRevision, snapshot,
+                generation: context.generation, scalars: context.scalars, complex: context.complexChanges.length > 0, complexChanges: context.complexChanges };
+            this.db.prepare('INSERT INTO publications VALUES(?,?,?,?)').run(publication.id, scope.target, publication.state, bounded(publication));
+            return publication;
+        });
+    }
+    publicationIntent(publication) {
+        return this.transaction(() => {
+            const previous = this.publication(publication);
+            if (previous.state !== 'preparing')
+                fail('blocked', 'Publication intent was already issued; verify its history instead of retrying.');
+            const next = { ...previous, state: 'commit_intent' };
+            const model = this.model(previous.target);
+            this.db.prepare('UPDATE ghidra_models SET data=? WHERE target=?').run(stable({ ...model, state: 'unknown' }), previous.target);
+            this.db.prepare('UPDATE publications SET state=?,data=? WHERE id=?').run(next.state, bounded(next), next.id);
+            return next;
+        });
+    }
+    unknownPublication(publication, detail) {
+        return this.transaction(() => {
+            const previous = this.publication(publication);
+            if (!['commit_intent', 'unknown'].includes(previous.state))
+                fail('binding', 'Uncertainty must retain an actual publication intent.');
+            const next = { ...previous, state: 'unknown', detail };
+            this.db.prepare('UPDATE publications SET state=?,data=? WHERE id=?').run(next.state, bounded(next), next.id);
+            return next;
+        });
+    }
+    finishPublication(publication, publishedRevision, result) {
+        version(publishedRevision);
+        return this.transaction(() => {
+            const previous = this.publication(publication);
+            if (!['commit_intent', 'unknown'].includes(previous.state) || publishedRevision !== previous.expectedRevision + 1)
+                fail('binding', 'Verified publication has an unexpected state or version.');
+            const context = this.context(previous), model = this.model(previous.target);
+            if (context.generation !== previous.generation)
+                fail('binding', 'Private context changed during publication; preserve both saved versions.');
+            this.writeContext(previous, previous.generation, { state: 'ready', baseRevision: publishedRevision, baseSnapshot: previous.snapshot,
+                workingSnapshot: previous.snapshot, viewEpoch: (context.viewEpoch ?? 0) + 1, scalars: [], complexChanges: [] });
+            this.db.prepare('UPDATE ghidra_models SET data=? WHERE target=?').run(stable({ ...model, state: 'ready', sharedRevision: publishedRevision, sharedSnapshot: previous.snapshot }), previous.target);
+            this.writeRequest(previous.request, 'applied', result);
+            const next = { ...previous, state: 'verified', publishedRevision };
+            this.db.prepare('UPDATE publications SET state=?,data=? WHERE id=?').run(next.state, bounded(next), next.id);
+            return next;
+        });
+    }
+    rejectPublication(publication, result) {
+        return this.transaction(() => {
+            const previous = this.publication(publication);
+            if (!['preparing', 'commit_intent'].includes(previous.state))
+                fail('blocked', 'An uncertain publication cannot be abandoned without proof.');
+            const model = this.model(previous.target), next = { ...previous, state: 'conflict', detail: result };
+            this.db.prepare('UPDATE ghidra_models SET data=? WHERE target=?').run(stable({ ...model, state: 'ready' }), previous.target);
+            this.db.prepare('UPDATE publications SET state=?,data=? WHERE id=?').run(next.state, bounded(next), next.id);
+            this.writeRequest(previous.request, 'failed', result);
+            return next;
+        });
+    }
+    publishedSince(target, revision) {
+        this.target(target);
+        version(revision);
+        return this.db.prepare("SELECT data FROM publications WHERE target=? AND state='verified' ORDER BY rowid").all(target)
+            .map(row => JSON.parse(String(row.data))).filter(item => item.publishedRevision > revision);
+    }
+    saveContext(scope, expectedGeneration, patch) {
+        return this.transaction(() => this.writeContext(scope, expectedGeneration, patch));
+    }
+    /** Snapshot and successful request acknowledgment enter the same durable transaction. */
+    completeSavedRequest(scope, request, expectedGeneration, patch, result) {
+        return this.transaction(() => {
+            const previous = this.context(scope), intent = this.request(request);
+            if (intent.context !== previous.id)
+                fail('binding', 'Saved operation belongs to a different working context.');
+            if (intent.state === 'applied' || intent.state === 'failed')
+                fail('idempotency', 'Completed request cannot change its working context.');
+            const context = this.writeContext(scope, expectedGeneration, patch);
+            const outcome = this.writeRequest(request, 'applied', result);
+            return { context, request: outcome };
+        });
+    }
+    writeContext(scope, expectedGeneration, patch) {
+        if (!Number.isSafeInteger(expectedGeneration) || expectedGeneration < 0)
+            fail('invalid', 'Invalid context generation.');
+        if (Object.keys(patch).some(key => !['state', 'baseRevision', 'baseSnapshot', 'workingSnapshot', 'viewEpoch', 'scalars', 'complexChanges', 'debugger', 'syncPolicy'].includes(key)) ||
+            patch.state !== undefined && !['opening', 'ready', 'stopped', 'needs_recovery'].includes(patch.state))
+            fail('invalid', 'Invalid context state update.');
+        if (patch.baseRevision !== undefined)
+            version(patch.baseRevision);
+        if (patch.viewEpoch !== undefined && (!Number.isSafeInteger(patch.viewEpoch) || patch.viewEpoch < 0))
+            fail('invalid', 'View epoch must be a nonnegative integer.');
+        if (patch.baseSnapshot)
+            this.knownSnapshot(patch.baseSnapshot);
+        if (patch.workingSnapshot)
+            this.knownSnapshot(patch.workingSnapshot);
+        if (patch.syncPolicy) {
+            const p = patch.syncPolicy;
+            if (Object.keys(p).some(k => !['publish', 'refresh'].includes(k)) || !['manual', 'after-edit', 'after-save'].includes(p.publish) || !['manual', 'before-edit'].includes(p.refresh))
+                fail('invalid', 'Invalid synchronization policy.');
+        }
+        if (patch.debugger) {
+            const state = patch.debugger;
+            if (typeof state.connected !== 'boolean' || !Array.isArray(state.traces) || state.traces.length > 64)
+                fail('invalid', 'Debugger trace state is malformed.');
+            const ids = new Set();
+            for (const trace of state.traces) {
+                if (!/^trace_[a-f0-9-]{36}$/.test(trace.id) || ids.has(trace.id) || !/^\d+$/.test(trace.snap) || !Number.isSafeInteger(trace.modules) || trace.modules < 0 || !Number.isSafeInteger(trace.threads) || trace.threads < 0 || typeof trace.connected !== 'boolean')
+                    fail('invalid', 'Saved trace identity or counts are malformed.');
+                text(trace.name, 512);
+                this.knownSnapshot(trace.snapshot);
+                ids.add(trace.id);
+                if (trace.thread !== undefined && !/^\d+$/.test(trace.thread))
+                    fail('invalid', 'Saved debugger thread is malformed.');
+            }
+            if (state.active !== undefined && !ids.has(state.active))
+                fail('invalid', 'Active trace must belong to the selected context.');
+        }
+        const previous = this.context(scope);
+        if (previous.generation !== expectedGeneration)
+            fail('binding', 'Context changed before its saved result could be recorded.');
+        const next = { ...previous, ...patch, generation: expectedGeneration + 1 };
+        if (next.state === 'ready' && (!next.baseRevision || !next.baseSnapshot || !next.workingSnapshot))
+            fail('binding', 'A ready context requires durable private and base snapshots.');
+        if (!Array.isArray(next.scalars) || !Array.isArray(next.complexChanges))
+            fail('invalid', 'Pending changes must be arrays.');
+        for (const request of next.complexChanges)
+            id(request);
+        if (new Set(next.complexChanges).size !== next.complexChanges.length)
+            fail('invalid', 'Complex change identities must be distinct.');
+        const fields = new Set();
+        for (const change of next.scalars) {
+            if (!/^(?:[A-Za-z0-9_]+:)?[a-f0-9]+$/.test(text(change.address, 128)) ||
+                !['function.name', 'comment.eol', 'comment.pre', 'comment.post', 'comment.plate', 'comment.repeatable'].includes(change.field))
+                fail('invalid', 'Scalar changes require a canonical address and a supported field.');
+            for (const value of [change.original, change.local, ...(change.conflict ? [change.conflict.shared] : [])]) {
+                if (value !== null && (typeof value !== 'string' || value.length > 16000 || value.includes('\0')))
+                    fail('invalid', 'Scalar values must be bounded strings or null.');
+            }
+            if (change.removed !== undefined && (change.removed !== true || change.local !== null || !next.complexChanges.length))
+                fail('invalid', 'Removed scalar fields require retained complex program state.');
+            if (change.field === 'function.name' && !change.removed && (change.local === null || !change.local.length || change.local.length > 512))
+                fail('invalid', 'Function name must be a nonempty bounded string.');
+            const field = change.address + ':' + change.field;
+            if (change.dependency !== undefined && !/^[a-f0-9]{64}$/.test(change.dependency))
+                fail('invalid', 'Scalar dependency fingerprint is malformed.');
+            if (fields.has(field))
+                fail('invalid', 'Scalar field must have one original/local comparison.');
+            fields.add(field);
+        }
+        this.db.prepare('UPDATE contexts SET generation=?,data=? WHERE id=?').run(next.generation, bounded(next), next.id);
+        return next;
+    }
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@eyeauras/insight-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Agent-facing durable sessions and isolated Ghidra research contexts",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "bin": {
+    "insight-cli": "./dist/src/bin.js"
+  },
+  "files": [
+    "README.md",
+    "dist/src",
+    "SKILL.md",
+    "skills",
+    "references",
+    "runtime",
+    "LICENSE",
+    ".cli-package-build.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node ../../scripts/prepare-package.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@eyeauras/cli-factory": "0.4.1",
+    "@eyeauras/cli-factory-ipc": "https://raw.githubusercontent.com/iXab3r/insight-cli/43f815a006711418bcffa47a7d99ef5c42424ca5/vendor/factory-ipc-a2094fb.tgz",
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "tar": "7.5.22",
+    "yauzl": "3.4.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iXab3r/insight-cli.git",
+    "directory": "skills/ghidra-coordinator"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "homepage": "https://github.com/iXab3r/insight-cli#readme",
+  "bugs": {
+    "url": "https://github.com/iXab3r/insight-cli/issues"
+  }
+}