@xenosystem/agent-interface-host 0.1.3

package/dist/state/SqliteAgentStateRepository.js

@@ -0,0 +1,777 @@
+import { closeSync, copyFileSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { basename, dirname, join, resolve } from 'node:path';
+import { safeAgentStateError, sanitizeConversation, sanitizeWorkspaceTree, serializeBoundedAgentState, } from './stateSanitizers.js';
+const SQLITE_SCHEMA_VERSION = 1;
+const MAX_LEGACY_FILES = 100_002;
+const MAX_LEGACY_FILE_BYTES = 128 * 1024 * 1024;
+const MAX_LEGACY_TOTAL_BYTES = 2 * 1024 * 1024 * 1024;
+const APPLICATION_ID = 0x58454e4f;
+/**
+ * Transactional state authority for both XENO Agent surfaces. Runtime/audit events remain in the
+ * append-only event journal; this database owns mutable workspace and conversation projections.
+ */
+export class SqliteAgentStateRepository {
+    databaseFile;
+    migrationReport;
+    database;
+    closed = false;
+    constructor(databaseFile, database, migrationReport) {
+        this.databaseFile = databaseFile;
+        this.database = database;
+        this.migrationReport = migrationReport;
+    }
+    static async open(options) {
+        const normalized = normalizeOptions(options);
+        ensureDirectory(dirname(normalized.databaseFile));
+        ensureDirectory(normalized.backupsDirectory);
+        ensureDirectory(normalized.reportsDirectory);
+        const releaseMigrationLock = acquireMigrationLock(normalized.migrationLockFile);
+        try {
+            const driver = await loadSqliteDriver();
+            let report;
+            if (existsSync(normalized.databaseFile)) {
+                report = inspectExistingDatabase(driver, normalized);
+            }
+            else {
+                report = activateInitialDatabase(driver, normalized);
+            }
+            const database = driver.open(normalized.databaseFile);
+            configureActiveDatabase(database);
+            validateSchema(database);
+            return new SqliteAgentStateRepository(normalized.databaseFile, database, report);
+        }
+        finally {
+            releaseMigrationLock();
+        }
+    }
+    async loadWorkspaces() {
+        try {
+            this.assertOpen();
+            const row = asRecord(this.database.prepare('SELECT json FROM workspace_state WHERE singleton = 1').get());
+            if (!row || typeof row.json !== 'string')
+                return { success: true, workspaces: [] };
+            return { success: true, workspaces: sanitizeWorkspaceTree(JSON.parse(row.json)) };
+        }
+        catch (error) {
+            return { success: false, workspaces: [], error: safeAgentStateError(error) };
+        }
+    }
+    async saveWorkspaces(input) {
+        try {
+            this.assertOpen();
+            if (!Array.isArray(input.workspaces)) {
+                return { success: false, error: 'Invalid workspace state: expected an array.' };
+            }
+            const json = serializeBoundedAgentState(sanitizeWorkspaceTree(input.workspaces), 'Workspace state');
+            inTransaction(this.database, () => {
+                this.database.prepare(`
+          INSERT INTO workspace_state(singleton, json, updated_at)
+          VALUES (1, ?, ?)
+          ON CONFLICT(singleton) DO UPDATE SET json = excluded.json, updated_at = excluded.updated_at
+        `).run(json, Date.now());
+                markPostMigrationWrite(this.database);
+            });
+            return { success: true };
+        }
+        catch (error) {
+            return { success: false, error: safeAgentStateError(error) };
+        }
+    }
+    async loadConversations() {
+        try {
+            this.assertOpen();
+            const rows = this.database.prepare('SELECT json FROM conversations ORDER BY id ASC').all();
+            const conversations = rows.map((value) => {
+                const row = asRecord(value);
+                if (!row || typeof row.json !== 'string')
+                    throw new Error('Conversation row is corrupt.');
+                const conversation = sanitizeConversation(JSON.parse(row.json));
+                if (!conversation)
+                    throw new Error('Conversation row has an invalid identity.');
+                return conversation;
+            });
+            return {
+                success: true,
+                conversations,
+                recoveredConversationIds: [],
+                corruptConversationFiles: [],
+            };
+        }
+        catch (error) {
+            return { success: false, conversations: [], error: safeAgentStateError(error) };
+        }
+    }
+    async saveConversation(input) {
+        try {
+            this.assertOpen();
+            const conversation = sanitizeConversation(input.conversation);
+            if (!conversation)
+                return { success: false, error: 'Invalid conversation state.' };
+            const id = String(conversation.id);
+            const json = serializeBoundedAgentState(conversation, `Conversation ${id}`);
+            inTransaction(this.database, () => {
+                this.database.prepare(`
+          INSERT INTO conversations(id, json, updated_at)
+          VALUES (?, ?, ?)
+          ON CONFLICT(id) DO UPDATE SET json = excluded.json, updated_at = excluded.updated_at
+        `).run(id, json, Date.now());
+                markPostMigrationWrite(this.database);
+            });
+            return { success: true };
+        }
+        catch (error) {
+            return { success: false, error: safeAgentStateError(error) };
+        }
+    }
+    async deleteConversation(input) {
+        try {
+            this.assertOpen();
+            const id = typeof input.conversationId === 'string' ? input.conversationId.trim().slice(0, 240) : '';
+            if (!id)
+                return { success: false, error: 'Invalid conversation ID.' };
+            inTransaction(this.database, () => {
+                this.database.prepare('DELETE FROM conversations WHERE id = ?').run(id);
+                markPostMigrationWrite(this.database);
+            });
+            return { success: true };
+        }
+        catch (error) {
+            return { success: false, error: safeAgentStateError(error) };
+        }
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.database.close();
+    }
+    assertOpen() {
+        if (this.closed)
+            throw new Error('Agent state repository is closed.');
+    }
+}
+export async function rollbackAgentStateMigration(options) {
+    const normalized = normalizeOptions(options);
+    if (!existsSync(normalized.databaseFile)) {
+        return { success: false, rollbackDirectory: null, error: 'No active Agent state database exists.' };
+    }
+    ensureDirectory(normalized.backupsDirectory);
+    const releaseMigrationLock = acquireMigrationLock(normalized.migrationLockFile);
+    try {
+        const driver = await loadSqliteDriver();
+        const database = driver.open(normalized.databaseFile);
+        let migrationId = null;
+        let writes = 0;
+        try {
+            configureActiveDatabase(database);
+            validateSchema(database);
+            migrationId = readMetadata(database, 'legacy_migration_id');
+            writes = Number.parseInt(readMetadata(database, 'post_migration_writes') || '0', 10);
+        }
+        finally {
+            database.close();
+        }
+        if (!migrationId) {
+            return { success: false, rollbackDirectory: null, error: 'The active database was not created from legacy state.' };
+        }
+        if (!Number.isFinite(writes) || writes !== 0) {
+            return {
+                success: false,
+                rollbackDirectory: null,
+                error: 'Rollback is no longer safe because the transactional store has accepted post-migration writes.',
+            };
+        }
+        const rollbackDirectory = join(normalized.backupsDirectory, `rollback-${timestampSlug(new Date())}-${migrationId.slice(0, 12)}`);
+        ensureDirectory(rollbackDirectory);
+        for (const suffix of ['', '-wal', '-shm']) {
+            const source = `${normalized.databaseFile}${suffix}`;
+            if (!existsSync(source))
+                continue;
+            renameSync(source, join(rollbackDirectory, `${basename(normalized.databaseFile)}${suffix}`));
+        }
+        return { success: true, rollbackDirectory, error: null };
+    }
+    catch (error) {
+        return { success: false, rollbackDirectory: null, error: safeAgentStateError(error) };
+    }
+    finally {
+        releaseMigrationLock();
+    }
+}
+function normalizeOptions(options) {
+    const databaseFile = requiredAbsolutePath(options.databaseFile, 'databaseFile');
+    const backupsDirectory = requiredAbsolutePath(options.backupsDirectory, 'backupsDirectory');
+    const reportsDirectory = requiredAbsolutePath(options.reportsDirectory, 'reportsDirectory');
+    const migrationLockFile = requiredAbsolutePath(options.migrationLockFile, 'migrationLockFile');
+    const legacyWorkspaceFile = optionalAbsolutePath(options.legacyWorkspaceFile);
+    const legacyConversationsDirectory = optionalAbsolutePath(options.legacyConversationsDirectory);
+    return {
+        databaseFile,
+        backupsDirectory,
+        reportsDirectory,
+        migrationLockFile,
+        ...(legacyWorkspaceFile ? { legacyWorkspaceFile } : {}),
+        ...(legacyConversationsDirectory ? { legacyConversationsDirectory } : {}),
+    };
+}
+async function loadSqliteDriver() {
+    const major = Number.parseInt(process.versions.node.split('.')[0] || '0', 10);
+    if (major >= 22) {
+        try {
+            const module = await import('node:sqlite');
+            return {
+                id: 'node:sqlite',
+                open: (path) => new module.DatabaseSync(path),
+            };
+        }
+        catch {
+            // Electron 33 embeds Node 20. Native packaged builds use the compatible fallback below.
+        }
+    }
+    try {
+        const require = createRequire(import.meta.url);
+        const loaded = require('better-sqlite3');
+        const Database = asDatabaseConstructor(loaded);
+        return { id: 'better-sqlite3', open: (path) => new Database(path) };
+    }
+    catch (error) {
+        throw new Error(`No compatible SQLite driver is available for Node ${process.versions.node}: ${safeAgentStateError(error)}`);
+    }
+}
+function asDatabaseConstructor(value) {
+    if (typeof value === 'function')
+        return value;
+    const record = asRecord(value);
+    if (record && typeof record.default === 'function') {
+        return record.default;
+    }
+    throw new Error('better-sqlite3 did not expose a database constructor.');
+}
+function activateInitialDatabase(driver, options) {
+    const started = new Date();
+    let inventory = emptyLegacyInventory();
+    let migrationId = `fresh-${createHash('sha256').update(options.databaseFile).digest('hex')}`;
+    const temporaryDatabase = `${options.databaseFile}.migrating-${process.pid}-${Date.now()}`;
+    let database = null;
+    try {
+        inventory = inventoryLegacyState(options, started);
+        migrationId = inventory.sourceFiles.length > 0
+            ? `legacy-${inventory.sourceFingerprint}`
+            : migrationId;
+        database = driver.open(temporaryDatabase);
+        configureMigrationDatabase(database);
+        createSchema(database);
+        inTransaction(database, () => {
+            database?.prepare('INSERT INTO workspace_state(singleton, json, updated_at) VALUES (1, ?, ?)')
+                .run(serializeBoundedAgentState(inventory.workspace, 'Migrated workspace state'), Date.now());
+            const insertConversation = database?.prepare('INSERT INTO conversations(id, json, updated_at) VALUES (?, ?, ?)');
+            for (const conversation of inventory.conversations) {
+                const id = String(conversation.id);
+                insertConversation?.run(id, serializeBoundedAgentState(conversation, `Migrated conversation ${id}`), Date.now());
+            }
+            writeMetadata(database, 'created_by_driver', driver.id);
+            writeMetadata(database, 'legacy_migration_id', inventory.sourceFiles.length > 0 ? migrationId : '');
+            writeMetadata(database, 'post_migration_writes', '0');
+            database?.prepare(`
+        INSERT INTO migration_ledger(
+          id, status, source_fingerprint, backup_directory, counts_json, recovered_sources_json,
+          started_at, completed_at, error
+        ) VALUES (?, 'complete', ?, ?, ?, ?, ?, ?, NULL)
+      `).run(migrationId, inventory.sourceFiles.length > 0 ? inventory.sourceFingerprint : null, inventory.backupDirectory, JSON.stringify({ workspaces: inventory.workspace.length, conversations: inventory.conversations.length }), JSON.stringify(inventory.recoveredSources), started.toISOString(), new Date().toISOString());
+        });
+        validateImportedState(database, inventory);
+        database.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+        database.close();
+        database = null;
+        fsyncFile(temporaryDatabase);
+        renameSync(temporaryDatabase, options.databaseFile);
+        const completed = new Date();
+        const report = {
+            schemaVersion: 1,
+            migrationId,
+            status: inventory.sourceFiles.length > 0 ? 'migrated' : 'fresh',
+            startedAt: started.toISOString(),
+            completedAt: completed.toISOString(),
+            databaseFile: options.databaseFile,
+            sourceFingerprint: inventory.sourceFiles.length > 0 ? inventory.sourceFingerprint : null,
+            backupDirectory: inventory.backupDirectory,
+            workspaceCount: inventory.workspace.length,
+            conversationCount: inventory.conversations.length,
+            recoveredSources: inventory.recoveredSources,
+            sourceFiles: inventory.sourceFiles,
+            reportFile: null,
+            error: null,
+        };
+        report.reportFile = writeMigrationReport(options.reportsDirectory, report);
+        return report;
+    }
+    catch (error) {
+        if (error instanceof LegacyStateInventoryError)
+            inventory = error.inventory;
+        if (inventory.sourceFiles.length > 0)
+            migrationId = `legacy-${inventory.sourceFingerprint}`;
+        database?.close();
+        if (existsSync(temporaryDatabase))
+            rmSync(temporaryDatabase, { force: true });
+        const completed = new Date();
+        const report = {
+            schemaVersion: 1,
+            migrationId,
+            status: 'failed',
+            startedAt: started.toISOString(),
+            completedAt: completed.toISOString(),
+            databaseFile: options.databaseFile,
+            sourceFingerprint: inventory.sourceFiles.length > 0 ? inventory.sourceFingerprint : null,
+            backupDirectory: inventory.backupDirectory,
+            workspaceCount: inventory.workspace.length,
+            conversationCount: inventory.conversations.length,
+            recoveredSources: inventory.recoveredSources,
+            sourceFiles: inventory.sourceFiles,
+            reportFile: null,
+            error: safeAgentStateError(error),
+        };
+        report.reportFile = writeMigrationReport(options.reportsDirectory, report);
+        throw new Error(`Agent state migration failed without activation: ${report.error}`);
+    }
+}
+function inspectExistingDatabase(driver, options) {
+    const started = new Date();
+    const database = driver.open(options.databaseFile);
+    try {
+        configureActiveDatabase(database);
+        validateSchema(database);
+        const workspaceCount = Number(asRecord(database.prepare('SELECT COUNT(*) AS count FROM workspace_state').get())?.count || 0);
+        const conversationCount = Number(asRecord(database.prepare('SELECT COUNT(*) AS count FROM conversations').get())?.count || 0);
+        const ledger = asRecord(database.prepare(`
+      SELECT id, source_fingerprint, backup_directory, recovered_sources_json
+      FROM migration_ledger
+      WHERE status = 'complete'
+      ORDER BY completed_at DESC
+      LIMIT 1
+    `).get());
+        const completed = new Date();
+        return {
+            schemaVersion: 1,
+            migrationId: typeof ledger?.id === 'string' ? ledger.id : 'existing-database',
+            status: 'existing',
+            startedAt: started.toISOString(),
+            completedAt: completed.toISOString(),
+            databaseFile: options.databaseFile,
+            sourceFingerprint: typeof ledger?.source_fingerprint === 'string' ? ledger.source_fingerprint : null,
+            backupDirectory: typeof ledger?.backup_directory === 'string' ? ledger.backup_directory : null,
+            workspaceCount,
+            conversationCount,
+            recoveredSources: parseStringArray(ledger?.recovered_sources_json),
+            sourceFiles: [],
+            reportFile: null,
+            error: null,
+        };
+    }
+    finally {
+        database.close();
+    }
+}
+function inventoryLegacyState(options, started) {
+    let inventory = emptyLegacyInventory();
+    try {
+        const candidates = legacySourceCandidates(options);
+        if (candidates.length > MAX_LEGACY_FILES) {
+            throw new Error(`Legacy state contains more than ${MAX_LEGACY_FILES} recognized files.`);
+        }
+        let totalBytes = 0;
+        const sourceFiles = candidates.map((candidate) => {
+            const info = inspectRegularFile(candidate.source);
+            if (info.size > MAX_LEGACY_FILE_BYTES) {
+                throw new Error(`Legacy state file ${candidate.source} exceeds the per-file migration limit.`);
+            }
+            totalBytes += info.size;
+            if (totalBytes > MAX_LEGACY_TOTAL_BYTES) {
+                throw new Error('Legacy state exceeds the total migration size limit.');
+            }
+            return {
+                source: candidate.source,
+                backupRelativePath: candidate.backupRelativePath,
+                bytes: info.size,
+                sha256: sha256File(candidate.source),
+            };
+        });
+        const sourceFingerprint = createHash('sha256')
+            .update(sourceFiles.map((file) => `${file.backupRelativePath}\0${file.bytes}\0${file.sha256}`).join('\n'))
+            .digest('hex');
+        const backupDirectory = sourceFiles.length > 0
+            ? join(options.backupsDirectory, `legacy-${timestampSlug(started)}-${sourceFingerprint.slice(0, 12)}`)
+            : null;
+        inventory = { ...inventory, sourceFiles, sourceFingerprint, backupDirectory };
+        if (backupDirectory)
+            backupLegacySources(sourceFiles, backupDirectory, sourceFingerprint, started);
+        const recoveredSources = [];
+        const workspace = readLegacyWorkspace(options.legacyWorkspaceFile, recoveredSources);
+        const conversations = readLegacyConversations(options.legacyConversationsDirectory, recoveredSources);
+        return { ...inventory, workspace, conversations, recoveredSources };
+    }
+    catch (error) {
+        throw new LegacyStateInventoryError(safeAgentStateError(error), inventory);
+    }
+}
+class LegacyStateInventoryError extends Error {
+    inventory;
+    constructor(message, inventory) {
+        super(message);
+        this.name = 'LegacyStateInventoryError';
+        this.inventory = inventory;
+    }
+}
+function emptyLegacyInventory() {
+    return {
+        sourceFiles: [],
+        sourceFingerprint: createHash('sha256').update('').digest('hex'),
+        workspace: [],
+        conversations: [],
+        recoveredSources: [],
+        backupDirectory: null,
+    };
+}
+function legacySourceCandidates(options) {
+    const candidates = [];
+    if (options.legacyWorkspaceFile) {
+        for (const [path, name] of [
+            [options.legacyWorkspaceFile, 'workspaces.json'],
+            [`${options.legacyWorkspaceFile}.bak`, 'workspaces.json.bak'],
+        ]) {
+            if (existsSync(path))
+                candidates.push({ source: path, backupRelativePath: join('workspace', name) });
+        }
+    }
+    if (options.legacyConversationsDirectory && existsSync(options.legacyConversationsDirectory)) {
+        const directoryInfo = lstatSync(options.legacyConversationsDirectory);
+        if (!directoryInfo.isDirectory() || directoryInfo.isSymbolicLink()) {
+            throw new Error('Legacy conversations path must be a real directory, not a link.');
+        }
+        for (const entry of readdirSync(options.legacyConversationsDirectory).sort()) {
+            if (!entry.endsWith('.json') && !entry.endsWith('.json.bak'))
+                continue;
+            candidates.push({
+                source: join(options.legacyConversationsDirectory, entry),
+                backupRelativePath: join('conversations', entry),
+            });
+        }
+    }
+    return candidates.sort((left, right) => left.backupRelativePath.localeCompare(right.backupRelativePath));
+}
+function backupLegacySources(files, backupDirectory, sourceFingerprint, started) {
+    if (existsSync(backupDirectory))
+        throw new Error(`Migration backup already exists: ${backupDirectory}`);
+    ensureDirectory(backupDirectory);
+    for (const file of files) {
+        const target = join(backupDirectory, file.backupRelativePath);
+        ensureDirectory(dirname(target));
+        copyFileSync(file.source, target);
+        fsyncFile(target);
+        if (sha256File(target) !== file.sha256) {
+            throw new Error(`Backup verification failed for ${file.source}.`);
+        }
+    }
+    const manifest = {
+        schemaVersion: 1,
+        createdAt: started.toISOString(),
+        sourceFingerprint,
+        files,
+    };
+    atomicWriteText(join(backupDirectory, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+function readLegacyWorkspace(path, recoveredSources) {
+    if (!path || (!existsSync(path) && !existsSync(`${path}.bak`)))
+        return [];
+    const parsed = readRecoverableJson(path, recoveredSources);
+    if (!Array.isArray(parsed))
+        throw new Error('Legacy workspace state is not an array.');
+    return sanitizeWorkspaceTree(parsed);
+}
+function readLegacyConversations(directory, recoveredSources) {
+    if (!directory || !existsSync(directory))
+        return [];
+    const baseNames = new Set();
+    for (const entry of readdirSync(directory)) {
+        if (entry.endsWith('.json'))
+            baseNames.add(entry);
+        else if (entry.endsWith('.json.bak'))
+            baseNames.add(entry.slice(0, -4));
+    }
+    const conversations = [];
+    const ids = new Set();
+    for (const name of [...baseNames].sort()) {
+        const parsed = readRecoverableJson(join(directory, name), recoveredSources);
+        const conversation = sanitizeConversation(parsed);
+        if (!conversation)
+            throw new Error(`Legacy conversation ${name} has an invalid identity.`);
+        const id = String(conversation.id);
+        if (ids.has(id))
+            throw new Error(`Legacy state contains duplicate conversation ID ${id}.`);
+        ids.add(id);
+        conversations.push(conversation);
+    }
+    return conversations;
+}
+function readRecoverableJson(primaryPath, recoveredSources) {
+    if (existsSync(primaryPath)) {
+        try {
+            inspectRegularFile(primaryPath);
+            return JSON.parse(readFileSync(primaryPath, 'utf8'));
+        }
+        catch (primaryError) {
+            const backupPath = `${primaryPath}.bak`;
+            if (!existsSync(backupPath)) {
+                throw new Error(`Legacy state ${primaryPath} is corrupt and has no valid backup: ${safeAgentStateError(primaryError)}`);
+            }
+            try {
+                inspectRegularFile(backupPath);
+                const value = JSON.parse(readFileSync(backupPath, 'utf8'));
+                recoveredSources.push(basename(backupPath));
+                return value;
+            }
+            catch (backupError) {
+                throw new Error(`Legacy state ${primaryPath} and its backup are corrupt: ${safeAgentStateError(backupError)}`);
+            }
+        }
+    }
+    const backupPath = `${primaryPath}.bak`;
+    inspectRegularFile(backupPath);
+    recoveredSources.push(basename(backupPath));
+    return JSON.parse(readFileSync(backupPath, 'utf8'));
+}
+function configureMigrationDatabase(database) {
+    database.exec(`
+    PRAGMA journal_mode = DELETE;
+    PRAGMA synchronous = FULL;
+    PRAGMA foreign_keys = ON;
+    PRAGMA trusted_schema = OFF;
+    PRAGMA busy_timeout = 5000;
+    PRAGMA application_id = ${APPLICATION_ID};
+  `);
+}
+function configureActiveDatabase(database) {
+    database.exec(`
+    PRAGMA journal_mode = WAL;
+    PRAGMA synchronous = FULL;
+    PRAGMA foreign_keys = ON;
+    PRAGMA trusted_schema = OFF;
+    PRAGMA busy_timeout = 5000;
+    PRAGMA wal_autocheckpoint = 1000;
+  `);
+}
+function createSchema(database) {
+    database.exec(`
+    CREATE TABLE IF NOT EXISTS metadata (
+      key TEXT PRIMARY KEY NOT NULL,
+      value TEXT NOT NULL
+    ) STRICT;
+    CREATE TABLE IF NOT EXISTS workspace_state (
+      singleton INTEGER PRIMARY KEY NOT NULL CHECK(singleton = 1),
+      json TEXT NOT NULL CHECK(json_valid(json)),
+      updated_at INTEGER NOT NULL
+    ) STRICT;
+    CREATE TABLE IF NOT EXISTS conversations (
+      id TEXT PRIMARY KEY NOT NULL,
+      json TEXT NOT NULL CHECK(json_valid(json)),
+      updated_at INTEGER NOT NULL
+    ) STRICT;
+    CREATE TABLE IF NOT EXISTS migration_ledger (
+      id TEXT PRIMARY KEY NOT NULL,
+      status TEXT NOT NULL CHECK(status IN ('complete', 'failed')),
+      source_fingerprint TEXT,
+      backup_directory TEXT,
+      counts_json TEXT NOT NULL CHECK(json_valid(counts_json)),
+      recovered_sources_json TEXT NOT NULL CHECK(json_valid(recovered_sources_json)),
+      started_at TEXT NOT NULL,
+      completed_at TEXT NOT NULL,
+      error TEXT
+    ) STRICT;
+    PRAGMA user_version = ${SQLITE_SCHEMA_VERSION};
+  `);
+}
+function validateSchema(database) {
+    const version = Number(asRecord(database.prepare('PRAGMA user_version').get())?.user_version);
+    if (version !== SQLITE_SCHEMA_VERSION) {
+        throw new Error(`Unsupported Agent state schema ${version}; expected ${SQLITE_SCHEMA_VERSION}.`);
+    }
+    const integrity = asRecord(database.prepare('PRAGMA quick_check').get());
+    const status = integrity ? Object.values(integrity)[0] : undefined;
+    if (status !== 'ok')
+        throw new Error(`Agent state integrity check failed: ${String(status || 'unknown')}.`);
+    for (const table of ['metadata', 'workspace_state', 'conversations', 'migration_ledger']) {
+        const row = asRecord(database.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").get(table));
+        if (row?.name !== table)
+            throw new Error(`Agent state database is missing table ${table}.`);
+    }
+}
+function validateImportedState(database, inventory) {
+    validateSchema(database);
+    const workspaceRow = asRecord(database.prepare('SELECT json FROM workspace_state WHERE singleton = 1').get());
+    if (typeof workspaceRow?.json !== 'string' || workspaceRow.json !== serializeBoundedAgentState(inventory.workspace, 'Workspace state')) {
+        throw new Error('Workspace migration equivalence check failed.');
+    }
+    const rows = database.prepare('SELECT id, json FROM conversations ORDER BY id ASC').all().map(asRecord);
+    if (rows.length !== inventory.conversations.length)
+        throw new Error('Conversation migration count check failed.');
+    const expected = [...inventory.conversations].sort((left, right) => String(left.id).localeCompare(String(right.id)));
+    for (let index = 0; index < expected.length; index += 1) {
+        const actual = rows[index];
+        const conversation = expected[index];
+        if (!actual || !conversation || actual.id !== conversation.id || actual.json !== serializeBoundedAgentState(conversation, `Conversation ${String(conversation.id)}`)) {
+            throw new Error(`Conversation migration equivalence check failed at index ${index}.`);
+        }
+    }
+}
+function inTransaction(database, action) {
+    database.exec('BEGIN IMMEDIATE');
+    try {
+        const result = action();
+        database.exec('COMMIT');
+        return result;
+    }
+    catch (error) {
+        try {
+            database.exec('ROLLBACK');
+        }
+        catch {
+            // Preserve the original transaction error.
+        }
+        throw error;
+    }
+}
+function markPostMigrationWrite(database) {
+    const current = Number.parseInt(readMetadata(database, 'post_migration_writes') || '0', 10);
+    writeMetadata(database, 'post_migration_writes', String(Number.isFinite(current) ? current + 1 : 1));
+}
+function readMetadata(database, key) {
+    const row = asRecord(database.prepare('SELECT value FROM metadata WHERE key = ?').get(key));
+    return typeof row?.value === 'string' ? row.value : null;
+}
+function writeMetadata(database, key, value) {
+    database.prepare(`
+    INSERT INTO metadata(key, value) VALUES (?, ?)
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value
+  `).run(key, value);
+}
+function inspectRegularFile(path) {
+    const info = lstatSync(path);
+    if (!info.isFile() || info.isSymbolicLink())
+        throw new Error(`Legacy state source is not a regular file: ${path}`);
+    return { size: info.size };
+}
+function sha256File(path) {
+    return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+function acquireMigrationLock(path) {
+    ensureDirectory(dirname(path));
+    let handle;
+    try {
+        handle = openSync(path, 'wx');
+    }
+    catch {
+        throw new Error(`Agent state migration lock is already held: ${path}`);
+    }
+    try {
+        writeFileSync(handle, `${JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() })}\n`, 'utf8');
+        fsyncSync(handle);
+    }
+    catch (error) {
+        closeSync(handle);
+        if (existsSync(path))
+            unlinkSync(path);
+        throw error;
+    }
+    return () => {
+        try {
+            closeSync(handle);
+        }
+        finally {
+            if (existsSync(path))
+                unlinkSync(path);
+        }
+    };
+}
+function writeMigrationReport(reportsDirectory, report) {
+    ensureDirectory(reportsDirectory);
+    const path = join(reportsDirectory, `state-migration-${timestampSlug(new Date(report.completedAt))}-${report.migrationId.slice(0, 12)}.md`);
+    const lines = [
+        '# XENO Agent State Migration Report',
+        '',
+        `- Status: ${report.status}`,
+        `- Migration ID: ${report.migrationId}`,
+        `- Started: ${report.startedAt}`,
+        `- Completed: ${report.completedAt}`,
+        `- Database: ${report.databaseFile}`,
+        `- Source fingerprint: ${report.sourceFingerprint || '(fresh profile)'}`,
+        `- Backup: ${report.backupDirectory || '(none)'}`,
+        `- Workspaces: ${report.workspaceCount}`,
+        `- Conversations: ${report.conversationCount}`,
+        `- Recovered sources: ${report.recoveredSources.length}`,
+        `- Source files: ${report.sourceFiles.length}`,
+        `- Error: ${report.error || '(none)'}`,
+        '',
+        report.status === 'migrated'
+            ? 'The legacy files remain byte-for-byte intact. Rollback is permitted only before the new database accepts a post-migration write.'
+            : 'No legacy state was modified by this operation.',
+        '',
+    ];
+    atomicWriteText(path, lines.join('\n'));
+    return path;
+}
+function atomicWriteText(path, contents) {
+    ensureDirectory(dirname(path));
+    const temporary = `${path}.tmp-${process.pid}-${Date.now()}`;
+    try {
+        writeFileSync(temporary, contents, 'utf8');
+        fsyncFile(temporary);
+        renameSync(temporary, path);
+    }
+    finally {
+        if (existsSync(temporary))
+            unlinkSync(temporary);
+    }
+}
+function fsyncFile(path) {
+    const handle = openSync(path, 'r+');
+    try {
+        fsyncSync(handle);
+    }
+    finally {
+        closeSync(handle);
+    }
+}
+function ensureDirectory(path) {
+    if (!existsSync(path))
+        mkdirSync(path, { recursive: true });
+}
+function timestampSlug(value) {
+    return value.toISOString().replace(/[:.]/g, '-').replace('T', '_').replace('Z', '');
+}
+function requiredAbsolutePath(value, field) {
+    const normalized = optionalAbsolutePath(value);
+    if (!normalized)
+        throw new Error(`Agent state ${field} is required.`);
+    return normalized;
+}
+function optionalAbsolutePath(value) {
+    return typeof value === 'string' && value.trim() ? resolve(value.trim()) : undefined;
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function parseStringArray(value) {
+    if (typeof value !== 'string')
+        return [];
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) ? parsed.filter((entry) => typeof entry === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=SqliteAgentStateRepository.js.map