noteconnection 1.6.8 → 1.8.0

package/dist/src/learning/store.js

@@ -0,0 +1,1240 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileBackedKnowledgeGraphStore = void 0;
+exports.isOpsAdapter = isOpsAdapter;
+exports.createFileBackedKnowledgeGraphStore = createFileBackedKnowledgeGraphStore;
+exports.normalizeKnowledgeGraphStoreBackend = normalizeKnowledgeGraphStoreBackend;
+exports.normalizeGraphDbSnapshotAdapterProvider = normalizeGraphDbSnapshotAdapterProvider;
+exports.normalizeGraphDbStoreOperationMode = normalizeGraphDbStoreOperationMode;
+exports.createFileGraphDbSnapshotAdapter = createFileGraphDbSnapshotAdapter;
+exports.createGraphDbSnapshotAdapter = createGraphDbSnapshotAdapter;
+exports.createKnowledgeGraphStore = createKnowledgeGraphStore;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function filterNodesFromSnapshot(snapshot, filter) {
+    let results = snapshot.atoms;
+    if (filter.nodeIds && filter.nodeIds.length > 0) {
+        const idSet = new Set(filter.nodeIds);
+        results = results.filter((atom) => idSet.has(atom.id) || idSet.has(atom.stableKey ?? ''));
+    }
+    if (filter.stableKey) {
+        results = results.filter((atom) => atom.stableKey === filter.stableKey);
+    }
+    if (filter.limit && filter.limit > 0) {
+        results = results.slice(0, filter.limit);
+    }
+    return results;
+}
+function filterEdgesFromSnapshot(snapshot, filter) {
+    let results = snapshot.relationEdges;
+    if (filter.fromNodeId) {
+        results = results.filter((edge) => edge.sourceAtomId === filter.fromNodeId);
+    }
+    if (filter.toNodeId) {
+        results = results.filter((edge) => edge.targetAtomId === filter.toNodeId);
+    }
+    if (filter.relationKind) {
+        results = results.filter((edge) => edge.relationKind === filter.relationKind);
+    }
+    if (filter.limit && filter.limit > 0) {
+        results = results.slice(0, filter.limit);
+    }
+    return results;
+}
+function findPathInSnapshot(snapshot, sourceId, targetId, maxDepth = 10) {
+    const adjacency = new Map();
+    for (const edge of snapshot.relationEdges) {
+        if (!adjacency.has(edge.sourceAtomId))
+            adjacency.set(edge.sourceAtomId, []);
+        adjacency.get(edge.sourceAtomId).push({ to: edge.targetAtomId, edge });
+    }
+    const visited = new Set();
+    const queue = [
+        { nodeId: sourceId, path: [sourceId], edges: [] }
+    ];
+    visited.add(sourceId);
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current.path.length > maxDepth)
+            continue;
+        if (current.nodeId === targetId) {
+            return {
+                path: current.path,
+                length: current.path.length - 1,
+                edges: current.edges,
+                found: true,
+            };
+        }
+        const neighbors = adjacency.get(current.nodeId) ?? [];
+        for (const { to, edge } of neighbors) {
+            if (!visited.has(to)) {
+                visited.add(to);
+                queue.push({
+                    nodeId: to,
+                    path: [...current.path, to],
+                    edges: [...current.edges, { from: edge.sourceAtomId, to: edge.targetAtomId, relation: edge.relationKind }],
+                });
+            }
+        }
+    }
+    return { path: [], length: 0, edges: [], found: false };
+}
+/** Check if a store adapter supports operation-level queries. */
+function isOpsAdapter(store) {
+    return typeof store.getCapabilities === 'function';
+}
+class FileBackedKnowledgeGraphStore {
+    constructor(options) {
+        this.options = options;
+        this.loaded = false;
+        /** Cached snapshot for operation-level queries without re-reading from disk. */
+        this.cachedSnapshot = null;
+    }
+    // ── M10.5: Operational Semantics ──
+    getCapabilities() {
+        return {
+            snapshotSupported: true,
+            nodeQuerySupported: true,
+            edgeQuerySupported: true,
+            pathQuerySupported: true,
+            writeSupported: true,
+            serverSideQuery: false, // File-backed loads full snapshot into memory
+        };
+    }
+    async getNode(atomId) {
+        const snapshot = await this.ensureSnapshot();
+        if (!snapshot)
+            return null;
+        return snapshot.atoms.find(a => a.id === atomId || a.stableKey === atomId) ?? null;
+    }
+    async queryNodes(filter) {
+        const snapshot = await this.ensureSnapshot();
+        if (!snapshot)
+            return [];
+        return filterNodesFromSnapshot(snapshot, filter);
+    }
+    async queryEdges(filter) {
+        const snapshot = await this.ensureSnapshot();
+        if (!snapshot)
+            return [];
+        return filterEdgesFromSnapshot(snapshot, filter);
+    }
+    async findPath(sourceId, targetId, maxDepth = 10) {
+        const snapshot = await this.ensureSnapshot();
+        if (!snapshot)
+            return { path: [], length: 0, edges: [], found: false };
+        return findPathInSnapshot(snapshot, sourceId, targetId, maxDepth);
+    }
+    async ensureSnapshot() {
+        if (this.cachedSnapshot)
+            return this.cachedSnapshot;
+        this.cachedSnapshot = await this.loadSnapshot();
+        return this.cachedSnapshot;
+    }
+    async loadSnapshot() {
+        const filePath = path.resolve(this.options.filePath);
+        try {
+            const content = await fs.promises.readFile(filePath, 'utf8');
+            const parsed = JSON.parse(content);
+            if ((parsed.schemaVersion !== 1 && parsed.schemaVersion !== 2) || !Array.isArray(parsed.atoms) || !Array.isArray(parsed.documents)) {
+                throw new Error('Invalid knowledge graph snapshot schema.');
+            }
+            this.loaded = true;
+            this.lastLoadAt = new Date().toISOString();
+            return parsed;
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code === 'ENOENT' || code === 'ENOTDIR') {
+                this.loaded = false;
+                this.lastError = undefined;
+                return null;
+            }
+            this.loaded = false;
+            this.lastError = String(error?.message || error);
+            throw error;
+        }
+    }
+    async saveSnapshot(snapshot) {
+        const filePath = path.resolve(this.options.filePath);
+        const directory = path.dirname(filePath);
+        const tempPath = `${filePath}.tmp`;
+        await fs.promises.mkdir(directory, { recursive: true });
+        const serialized = JSON.stringify(snapshot, null, 2);
+        try {
+            await fs.promises.writeFile(tempPath, serialized, 'utf8');
+            await fs.promises.rename(tempPath, filePath);
+            this.lastSaveAt = new Date().toISOString();
+            this.lastError = undefined;
+        }
+        catch (error) {
+            this.lastError = String(error?.message || error);
+            throw error;
+        }
+        finally {
+            try {
+                await fs.promises.unlink(tempPath);
+            }
+            catch (_cleanupError) {
+            }
+        }
+    }
+    getDiagnostics() {
+        const filePath = path.resolve(this.options.filePath);
+        const caps = this.getCapabilities();
+        // Staleness tracking (GitNexus pattern): compare snapshot save time to file mtime
+        let staleSince;
+        let fileMtime;
+        try {
+            const stat = fs.statSync(filePath);
+            fileMtime = stat.mtime.toISOString();
+            if (this.lastSaveAt && stat.mtime > new Date(this.lastSaveAt)) {
+                staleSince = stat.mtime.toISOString();
+            }
+        }
+        catch { /* file may not exist yet */ }
+        return {
+            storeType: 'file',
+            location: filePath,
+            exists: fs.existsSync(filePath),
+            loaded: this.loaded,
+            lastLoadAt: this.lastLoadAt,
+            lastSaveAt: this.lastSaveAt,
+            lastError: this.lastError,
+            adapterId: 'file-backed-ops',
+            graphDbOperationMode: caps.serverSideQuery ? 'server-side-query' : 'snapshot-with-ops',
+            backendReady: this.loaded,
+            staleSince,
+            fileMtime,
+        };
+    }
+}
+exports.FileBackedKnowledgeGraphStore = FileBackedKnowledgeGraphStore;
+function createFileBackedKnowledgeGraphStore(options) {
+    return new FileBackedKnowledgeGraphStore(options);
+}
+function hasGraphQueryOpsPath(adapter) {
+    return typeof adapter.getNodeByOps === 'function'
+        || typeof adapter.queryNodesByOps === 'function'
+        || typeof adapter.queryEdgesByOps === 'function'
+        || typeof adapter.findPathByOps === 'function';
+}
+// Why ops-capable detection: Some graphdb adapters support fine-grained operations
+// (getNode, queryEdges, findPath) in addition to full-snapshot load/save. We detect
+// this via capability negotiation: check for *ByOps methods + explicit opsCapable flag
+// or getCapabilities().mode. This allows the same store interface to serve both
+// simple file-backed stores and advanced graphdb backends without changing callers.
+function hasOpsCapablePath(adapter) {
+    const hasSnapshotOpsMethods = typeof adapter.loadSnapshotByOps === 'function'
+        && typeof adapter.saveSnapshotByOps === 'function';
+    const hasQueryOpsMethods = hasGraphQueryOpsPath(adapter);
+    if (!hasSnapshotOpsMethods && !hasQueryOpsMethods)
+        return false;
+    if (adapter.opsCapable === true)
+        return true;
+    const caps = adapter.getCapabilities?.();
+    if (caps?.mode === 'ops_capable')
+        return true;
+    if (hasQueryOpsMethods) {
+        const nodeQuerySupported = caps?.nodeQuerySupported === true;
+        const edgeQuerySupported = caps?.edgeQuerySupported === true;
+        const pathQuerySupported = caps?.pathQuerySupported === true;
+        return nodeQuerySupported || edgeQuerySupported || pathQuerySupported;
+    }
+    return false;
+}
+function normalizeKnowledgeGraphStoreBackend(v) {
+    const valid = new Set(['file', 'graphdb', 'none', 'memory']);
+    const s = String(v ?? 'file').trim().toLowerCase();
+    if (s === 'memory')
+        return 'memory';
+    return valid.has(s) ? s : 'file';
+}
+function normalizeGraphDbSnapshotAdapterProvider(v) {
+    const s = String(v ?? 'file').trim().toLowerCase();
+    if (s === 'local-file' || s === 'file')
+        return 'file';
+    if (s === 'external_http' || s === 'remote-http' || s === 'service' || s === 'http')
+        return 'http';
+    if (s === 'sqlite' || s === 'embedded_sqlite' || s === 'embedded-sqlite' || s === 'embedded')
+        return 'sqlite';
+    if (s === 'none' || s === 'disabled' || s === 'fallback_only')
+        return 'none';
+    if (s === 'unknown')
+        return 'file';
+    return 'file';
+}
+function normalizeGraphDbStoreOperationMode(v) {
+    const s = String(v ?? 'snapshot').trim().toLowerCase();
+    if (s === 'snapshot' || s === 'snapshot_only')
+        return 'snapshot_only';
+    if (s === 'ops' || s === 'ops_preferred' || s === 'operations')
+        return 'ops_preferred';
+    return 'snapshot_only';
+}
+function createFileGraphDbSnapshotAdapter(options) {
+    const filePath = options?.filePath ?? '/tmp/notemd-kg-snapshot.json';
+    const store = new FileBackedKnowledgeGraphStore({ filePath });
+    return {
+        id: options?.id ?? 'file-graphdb-local',
+        provider: 'file',
+        opsCapable: true,
+        getCapabilities: () => ({
+            snapshotSupported: true, nodeQuerySupported: true,
+            edgeQuerySupported: true, pathQuerySupported: true,
+            writeSupported: true, serverSideQuery: false,
+            mode: 'ops_capable',
+            supportedReadOperations: ['load_snapshot', 'load_snapshot_by_ops', 'probe_snapshot_metadata'],
+            supportedWriteOperations: ['save_snapshot', 'save_snapshot_by_ops'],
+        }),
+        loadSnapshot: () => store.loadSnapshot(),
+        saveSnapshot: (snapshot) => store.saveSnapshot(snapshot),
+        loadSnapshotByOps: () => store.loadSnapshot(),
+        saveSnapshotByOps: (snapshot) => store.saveSnapshot(snapshot),
+        probeSnapshotMetadata: async () => {
+            const s = await store.loadSnapshot();
+            return s ? { schemaVersion: s.schemaVersion, savedAt: s.savedAt, atomCount: s.atoms.length, relationEdgeCount: s.relationEdges.length, temporalEdgeCount: s.temporalEdges.length, documentCount: s.documents.length } : null;
+        },
+        getDiagnostics: () => ({
+            ...store.getDiagnostics(),
+            capabilityMode: 'ops_capable',
+            supportedReadOperations: ['load_snapshot', 'load_snapshot_by_ops', 'probe_snapshot_metadata'],
+            supportedWriteOperations: ['save_snapshot', 'save_snapshot_by_ops'],
+            lastReadPath: 'ops',
+            lastWritePath: 'ops',
+        }),
+    };
+}
+function tryLoadNodeSqlite() {
+    try {
+        return require('node:sqlite');
+    }
+    catch {
+        return null;
+    }
+}
+function createSqliteGraphDbSnapshotAdapter(options) {
+    const sqliteModule = tryLoadNodeSqlite();
+    if (!sqliteModule || typeof sqliteModule.DatabaseSync !== 'function') {
+        return null;
+    }
+    const sqlitePath = path.resolve(String(options?.sqlitePath || options?.filePath || '/tmp/notemd-kg-snapshot.sqlite'));
+    fs.mkdirSync(path.dirname(sqlitePath), { recursive: true });
+    let db = null;
+    let closed = false;
+    const adapterId = options?.id ?? 'embedded-sqlite-graphdb';
+    let loaded = false;
+    let lastLoadAt = '';
+    let lastSaveAt = '';
+    let lastError = '';
+    let lastReadPath = 'ops';
+    let lastWritePath = 'ops';
+    const ensureDb = () => {
+        if (!db || closed) {
+            db = new sqliteModule.DatabaseSync(sqlitePath);
+            closed = false;
+        }
+        return db;
+    };
+    const ensureSchema = () => {
+        ensureDb().exec(`
+            PRAGMA journal_mode = WAL;
+            PRAGMA synchronous = NORMAL;
+            PRAGMA busy_timeout = 2000;
+            CREATE TABLE IF NOT EXISTS snapshot_store (
+                snapshot_id INTEGER PRIMARY KEY CHECK (snapshot_id = 1),
+                schema_version INTEGER NOT NULL,
+                saved_at TEXT NOT NULL,
+                payload_json TEXT NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS atoms (
+                atom_id TEXT PRIMARY KEY,
+                stable_key TEXT,
+                title TEXT NOT NULL,
+                source_path TEXT,
+                updated_at TEXT,
+                raw_json TEXT NOT NULL
+            );
+            CREATE INDEX IF NOT EXISTS idx_atoms_stable_key ON atoms(stable_key);
+            CREATE TABLE IF NOT EXISTS relation_edges (
+                edge_id TEXT PRIMARY KEY,
+                source_atom_id TEXT NOT NULL,
+                target_atom_id TEXT NOT NULL,
+                relation_kind TEXT NOT NULL,
+                confidence REAL NOT NULL,
+                raw_json TEXT NOT NULL
+            );
+            CREATE INDEX IF NOT EXISTS idx_relation_edges_source ON relation_edges(source_atom_id);
+            CREATE INDEX IF NOT EXISTS idx_relation_edges_target ON relation_edges(target_atom_id);
+            CREATE INDEX IF NOT EXISTS idx_relation_edges_kind ON relation_edges(relation_kind);
+        `);
+    };
+    const loadSnapshotRow = () => {
+        ensureSchema();
+        return ensureDb().prepare(`
+            SELECT schema_version, saved_at, payload_json
+            FROM snapshot_store
+            WHERE snapshot_id = 1
+        `).get();
+    };
+    const loadSnapshotPayload = () => {
+        const row = loadSnapshotRow();
+        if (!row || !row.payload_json) {
+            loaded = false;
+            return null;
+        }
+        const parsed = JSON.parse(String(row.payload_json));
+        if ((parsed.schemaVersion !== 1 && parsed.schemaVersion !== 2) || !Array.isArray(parsed.atoms) || !Array.isArray(parsed.documents)) {
+            throw new Error('Invalid sqlite knowledge graph snapshot schema.');
+        }
+        loaded = true;
+        lastLoadAt = new Date().toISOString();
+        lastError = '';
+        return parsed;
+    };
+    const replaceSnapshotData = (snapshot) => {
+        ensureSchema();
+        const activeDb = ensureDb();
+        activeDb.exec('BEGIN IMMEDIATE TRANSACTION');
+        try {
+            activeDb.exec('DELETE FROM snapshot_store');
+            activeDb.exec('DELETE FROM atoms');
+            activeDb.exec('DELETE FROM relation_edges');
+            activeDb.prepare(`
+                INSERT INTO snapshot_store (snapshot_id, schema_version, saved_at, payload_json)
+                VALUES (1, ?, ?, ?)
+            `).run(snapshot.schemaVersion, snapshot.savedAt, JSON.stringify(snapshot));
+            const insertAtom = activeDb.prepare(`
+                INSERT INTO atoms (atom_id, stable_key, title, source_path, updated_at, raw_json)
+                VALUES (?, ?, ?, ?, ?, ?)
+            `);
+            snapshot.atoms.forEach((atom) => {
+                insertAtom.run(atom.id, atom.stableKey || '', atom.title, atom.sourcePath || '', atom.updatedAt || '', JSON.stringify(atom));
+            });
+            const insertRelationEdge = activeDb.prepare(`
+                INSERT INTO relation_edges (edge_id, source_atom_id, target_atom_id, relation_kind, confidence, raw_json)
+                VALUES (?, ?, ?, ?, ?, ?)
+            `);
+            snapshot.relationEdges.forEach((edge) => {
+                insertRelationEdge.run(edge.id, edge.sourceAtomId, edge.targetAtomId, edge.relationKind, Number(edge.confidence || 0), JSON.stringify(edge));
+            });
+            activeDb.exec('COMMIT');
+            loaded = true;
+            lastSaveAt = new Date().toISOString();
+            lastError = '';
+        }
+        catch (error) {
+            try {
+                activeDb.exec('ROLLBACK');
+            }
+            catch {
+            }
+            lastError = String(error?.message || error);
+            throw error;
+        }
+    };
+    const mapNodeRows = (rows) => rows
+        .map((row) => {
+        try {
+            return JSON.parse(String(row.raw_json || 'null'));
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((atom) => Boolean(atom && typeof atom === 'object'));
+    const mapEdgeRows = (rows) => rows
+        .map((row) => {
+        try {
+            return JSON.parse(String(row.raw_json || 'null'));
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((edge) => Boolean(edge && typeof edge === 'object'));
+    const buildInClause = (values) => ({
+        placeholders: values.map(() => '?').join(', '),
+        params: values,
+    });
+    return {
+        id: adapterId,
+        provider: 'sqlite',
+        opsCapable: true,
+        getCapabilities: () => ({
+            snapshotSupported: true,
+            nodeQuerySupported: true,
+            edgeQuerySupported: true,
+            pathQuerySupported: true,
+            writeSupported: true,
+            serverSideQuery: true,
+            mode: 'ops_capable',
+            supportedReadOperations: ['load_snapshot', 'get_node', 'query_nodes', 'query_edges', 'find_path', 'probe_snapshot_metadata'],
+            supportedWriteOperations: ['save_snapshot'],
+        }),
+        loadSnapshot: async () => {
+            lastReadPath = 'ops';
+            try {
+                return loadSnapshotPayload();
+            }
+            catch (error) {
+                loaded = false;
+                lastError = String(error?.message || error);
+                throw error;
+            }
+        },
+        saveSnapshot: async (snapshot) => {
+            lastWritePath = 'ops';
+            replaceSnapshotData(snapshot);
+        },
+        probeSnapshotMetadata: async () => {
+            ensureSchema();
+            const snapshotRow = loadSnapshotRow();
+            if (!snapshotRow) {
+                return null;
+            }
+            const activeDb = ensureDb();
+            const atomCountRow = activeDb.prepare('SELECT COUNT(*) AS count FROM atoms').get();
+            const relationCountRow = activeDb.prepare('SELECT COUNT(*) AS count FROM relation_edges').get();
+            const snapshot = loadSnapshotPayload();
+            return {
+                schemaVersion: Number(snapshotRow.schema_version || snapshot?.schemaVersion || 1),
+                savedAt: String(snapshotRow.saved_at || snapshot?.savedAt || ''),
+                atomCount: Number(atomCountRow?.count || 0),
+                relationEdgeCount: Number(relationCountRow?.count || 0),
+                temporalEdgeCount: snapshot?.temporalEdges.length || 0,
+                documentCount: snapshot?.documents.length || 0,
+            };
+        },
+        loadSnapshotByOps: async () => {
+            lastReadPath = 'ops';
+            return loadSnapshotPayload();
+        },
+        saveSnapshotByOps: async (snapshot) => {
+            lastWritePath = 'ops';
+            replaceSnapshotData(snapshot);
+        },
+        getNodeByOps: async (atomId) => {
+            ensureSchema();
+            lastReadPath = 'ops';
+            const normalizedId = String(atomId || '').trim();
+            if (!normalizedId) {
+                return null;
+            }
+            const row = ensureDb().prepare(`
+                SELECT raw_json
+                FROM atoms
+                WHERE atom_id = ? OR stable_key = ?
+                LIMIT 1
+            `).get(normalizedId, normalizedId);
+            return mapNodeRows(row ? [row] : [])[0] || null;
+        },
+        queryNodesByOps: async (filter) => {
+            ensureSchema();
+            lastReadPath = 'ops';
+            const clauses = [];
+            const params = [];
+            if (Array.isArray(filter.nodeIds) && filter.nodeIds.length > 0) {
+                const normalizedIds = Array.from(new Set(filter.nodeIds.map((item) => String(item || '').trim()).filter(Boolean)));
+                if (normalizedIds.length > 0) {
+                    const inClause = buildInClause(normalizedIds);
+                    clauses.push(`(atom_id IN (${inClause.placeholders}) OR stable_key IN (${inClause.placeholders}))`);
+                    params.push(...inClause.params, ...inClause.params);
+                }
+            }
+            if (String(filter.stableKey || '').trim()) {
+                clauses.push('stable_key = ?');
+                params.push(String(filter.stableKey).trim());
+            }
+            let sql = 'SELECT raw_json FROM atoms';
+            if (clauses.length > 0) {
+                sql += ` WHERE ${clauses.join(' AND ')}`;
+            }
+            sql += ' ORDER BY atom_id ASC';
+            if (filter.limit && filter.limit > 0) {
+                sql += ` LIMIT ${Math.max(1, Math.floor(filter.limit))}`;
+            }
+            return mapNodeRows(ensureDb().prepare(sql).all(...params));
+        },
+        queryEdgesByOps: async (filter) => {
+            ensureSchema();
+            lastReadPath = 'ops';
+            const clauses = [];
+            const params = [];
+            if (String(filter.fromNodeId || '').trim()) {
+                clauses.push('source_atom_id = ?');
+                params.push(String(filter.fromNodeId).trim());
+            }
+            if (String(filter.toNodeId || '').trim()) {
+                clauses.push('target_atom_id = ?');
+                params.push(String(filter.toNodeId).trim());
+            }
+            if (String(filter.relationKind || '').trim()) {
+                clauses.push('relation_kind = ?');
+                params.push(String(filter.relationKind).trim());
+            }
+            let sql = 'SELECT raw_json FROM relation_edges';
+            if (clauses.length > 0) {
+                sql += ` WHERE ${clauses.join(' AND ')}`;
+            }
+            sql += ' ORDER BY edge_id ASC';
+            if (filter.limit && filter.limit > 0) {
+                sql += ` LIMIT ${Math.max(1, Math.floor(filter.limit))}`;
+            }
+            return mapEdgeRows(ensureDb().prepare(sql).all(...params));
+        },
+        findPathByOps: async (sourceId, targetId, maxDepth = 10) => {
+            ensureSchema();
+            lastReadPath = 'ops';
+            const source = String(sourceId || '').trim();
+            const target = String(targetId || '').trim();
+            if (!source || !target) {
+                return { path: [], length: 0, edges: [], found: false };
+            }
+            const rows = ensureDb().prepare(`
+                SELECT source_atom_id, target_atom_id, relation_kind
+                FROM relation_edges
+            `).all();
+            const adjacency = new Map();
+            rows.forEach((row) => {
+                const from = String(row.source_atom_id || '').trim();
+                const to = String(row.target_atom_id || '').trim();
+                if (!from || !to) {
+                    return;
+                }
+                if (!adjacency.has(from)) {
+                    adjacency.set(from, []);
+                }
+                adjacency.get(from)?.push({
+                    to,
+                    relation: String(row.relation_kind || '').trim() || undefined,
+                });
+            });
+            const visited = new Set([source]);
+            const queue = [
+                { nodeId: source, path: [source], edges: [] },
+            ];
+            while (queue.length > 0) {
+                const current = queue.shift();
+                if (current.path.length > maxDepth) {
+                    continue;
+                }
+                if (current.nodeId === target) {
+                    return {
+                        path: current.path,
+                        length: current.path.length - 1,
+                        edges: current.edges,
+                        found: true,
+                    };
+                }
+                const neighbors = adjacency.get(current.nodeId) || [];
+                for (const neighbor of neighbors) {
+                    if (visited.has(neighbor.to)) {
+                        continue;
+                    }
+                    visited.add(neighbor.to);
+                    queue.push({
+                        nodeId: neighbor.to,
+                        path: [...current.path, neighbor.to],
+                        edges: [...current.edges, { from: current.nodeId, to: neighbor.to, relation: neighbor.relation }],
+                    });
+                }
+            }
+            return { path: [], length: 0, edges: [], found: false };
+        },
+        getDiagnostics: () => ({
+            storeType: 'graphdb',
+            location: sqlitePath,
+            exists: fs.existsSync(sqlitePath),
+            loaded,
+            lastLoadAt: lastLoadAt || undefined,
+            lastSaveAt: lastSaveAt || undefined,
+            lastError: lastError || undefined,
+            capabilityMode: 'ops_capable',
+            supportedReadOperations: ['load_snapshot', 'get_node', 'query_nodes', 'query_edges', 'find_path', 'probe_snapshot_metadata'],
+            supportedWriteOperations: ['save_snapshot'],
+            lastReadPath,
+            lastWritePath,
+            storageEngine: 'sqlite',
+        }),
+        close: () => {
+            try {
+                db?.close?.();
+            }
+            catch {
+            }
+            finally {
+                db = null;
+                closed = true;
+            }
+        },
+    };
+}
+function createGraphDbSnapshotAdapter(options) {
+    const rawProvider = options?.provider;
+    const provider = normalizeGraphDbSnapshotAdapterProvider(rawProvider);
+    if (provider === 'none')
+        return null;
+    if (provider === 'file') {
+        const fileAdapter = createFileGraphDbSnapshotAdapter({
+            provider: 'file',
+            filePath: options?.filePath,
+            id: (options?.id ?? options?.fileAdapterId ?? options?.adapterId),
+        });
+        if (!fileAdapter)
+            return null;
+        return fileAdapter;
+    }
+    if (provider === 'sqlite') {
+        const sqliteAdapter = createSqliteGraphDbSnapshotAdapter({
+            provider: 'sqlite',
+            filePath: options?.filePath,
+            sqlitePath: options?.sqlitePath,
+            id: (options?.id ?? options?.sqliteAdapterId ?? options?.adapterId),
+        });
+        if (!sqliteAdapter)
+            return null;
+        return sqliteAdapter;
+    }
+    // HTTP adapter — real HTTP communication with graphdb endpoint
+    const httpEndpoint = (options?.httpEndpoint ?? options?.baseUrl);
+    if (provider === 'http' && httpEndpoint) {
+        const endpoint = httpEndpoint.replace(/\/$/, '');
+        const snapUrl = `${endpoint}/snapshot`;
+        const nodeUrl = `${endpoint}/ops/node`;
+        const nodesUrl = `${endpoint}/ops/nodes`;
+        const edgesUrl = `${endpoint}/ops/edges`;
+        const pathUrl = `${endpoint}/ops/path`;
+        let reqCount = 0;
+        let okCount = 0;
+        let failCount = 0;
+        let lastReqId = '';
+        let lastErrCode = '';
+        let lastStatusCode = 0;
+        const doFetch = async (requestUrl, method, body) => {
+            reqCount++;
+            const headers = body ? { 'Content-Type': 'application/json' } : {};
+            const res = await fetch(requestUrl, { method, headers, body: body ? JSON.stringify(body) : undefined });
+            lastReqId = res.headers.get('X-Request-Id') || 'http-graphdb-' + reqCount;
+            lastStatusCode = Math.max(0, Math.floor(Number(res.status || 0)));
+            if (res.ok)
+                okCount++;
+            else {
+                failCount++;
+                lastErrCode = res.headers.get('X-Error-Code') || String(res.status);
+            }
+            return res;
+        };
+        // Why circuit breaker: The HTTP graphdb adapter can fail transiently (network
+        // blips, backend restarts). Without a circuit breaker, every request would
+        // attempt the failing backend, causing latency spikes and cascading failures.
+        // After `circuitThreshold` consecutive failures, the circuit opens: subsequent
+        // requests fail immediately (fail-fast) instead of waiting for timeouts.
+        // This is the standard "fail-fast under proven failure" pattern (Netflix Hystrix).
+        const circuitThreshold = options?.httpCircuitFailureThreshold ?? options.httpCircuitFailureThreshold ?? 3;
+        const circuitCooldown = options?.httpCircuitCooldownMs ?? 8000;
+        const adapterId = (options?.id ?? options?.adapterId ?? options?.httpAdapterId ?? 'http-graphdb');
+        let consecutiveFailures = 0;
+        let circuitState = 'closed';
+        let shortCircuitCount = 0;
+        let circuitOpenedAt = '';
+        const checkCircuit = () => {
+            if (circuitState === 'open') {
+                shortCircuitCount++;
+                throw new Error('graphdb_http_circuit_open');
+            }
+        };
+        return {
+            id: adapterId,
+            provider: 'http',
+            opsCapable: true,
+            getCapabilities: () => ({
+                snapshotSupported: true, nodeQuerySupported: true,
+                edgeQuerySupported: true, pathQuerySupported: true,
+                writeSupported: true, serverSideQuery: true,
+                mode: 'ops_capable',
+                supportedReadOperations: ['load_snapshot', 'get_node', 'query_nodes', 'query_edges', 'find_path'],
+                supportedWriteOperations: ['save_snapshot'],
+            }),
+            loadSnapshot: async () => {
+                checkCircuit();
+                const res = await doFetch(snapUrl, 'GET');
+                if (!res.ok) {
+                    consecutiveFailures++;
+                    if (consecutiveFailures >= circuitThreshold) {
+                        circuitState = 'open';
+                        circuitOpenedAt = new Date().toISOString();
+                    }
+                    throw new Error('graphdb_http_request_failed:' + res.status);
+                }
+                consecutiveFailures = 0;
+                const data = await res.json();
+                return (data?.snapshot ?? data);
+            },
+            saveSnapshot: async (snapshot) => {
+                checkCircuit();
+                const res = await doFetch(snapUrl, 'POST', { snapshot });
+                if (!res.ok) {
+                    consecutiveFailures++;
+                    if (consecutiveFailures >= circuitThreshold) {
+                        circuitState = 'open';
+                        circuitOpenedAt = new Date().toISOString();
+                    }
+                    throw new Error('graphdb_http_request_failed:' + res.status);
+                }
+                consecutiveFailures = 0;
+            },
+            getNodeByOps: async (atomId) => {
+                checkCircuit();
+                const safeId = encodeURIComponent(String(atomId || '').trim());
+                if (!safeId) {
+                    return null;
+                }
+                const res = await doFetch(`${nodeUrl}/${safeId}`, 'GET');
+                if (res.status === 404) {
+                    return null;
+                }
+                if (!res.ok) {
+                    consecutiveFailures++;
+                    if (consecutiveFailures >= circuitThreshold) {
+                        circuitState = 'open';
+                        circuitOpenedAt = new Date().toISOString();
+                    }
+                    throw new Error('graphdb_http_request_failed:' + res.status);
+                }
+                consecutiveFailures = 0;
+                const payload = await res.json();
+                const node = payload?.node ?? payload?.atom ?? payload?.item ?? payload ?? null;
+                if (!node || typeof node !== 'object') {
+                    return null;
+                }
+                return node;
+            },
+            queryNodesByOps: async (filter) => {
+                checkCircuit();
+                const res = await doFetch(nodesUrl, 'POST', { filter: filter || {} });
+                if (!res.ok) {
+                    consecutiveFailures++;
+                    if (consecutiveFailures >= circuitThreshold) {
+                        circuitState = 'open';
+                        circuitOpenedAt = new Date().toISOString();
+                    }
+                    throw new Error('graphdb_http_request_failed:' + res.status);
+                }
+                consecutiveFailures = 0;
+                const payload = await res.json();
+                const nodes = payload?.nodes ?? payload?.atoms ?? payload?.items ?? [];
+                return Array.isArray(nodes) ? nodes.filter((item) => Boolean(item && typeof item === 'object')) : [];
+            },
+            queryEdgesByOps: async (filter) => {
+                checkCircuit();
+                const res = await doFetch(edgesUrl, 'POST', { filter: filter || {} });
+                if (!res.ok) {
+                    consecutiveFailures++;
+                    if (consecutiveFailures >= circuitThreshold) {
+                        circuitState = 'open';
+                        circuitOpenedAt = new Date().toISOString();
+                    }
+                    throw new Error('graphdb_http_request_failed:' + res.status);
+                }
+                consecutiveFailures = 0;
+                const payload = await res.json();
+                const edges = payload?.edges ?? payload?.relationEdges ?? payload?.items ?? [];
+                return Array.isArray(edges) ? edges.filter((item) => Boolean(item && typeof item === 'object')) : [];
+            },
+            findPathByOps: async (sourceId, targetId, maxDepth) => {
+                checkCircuit();
+                const res = await doFetch(pathUrl, 'POST', {
+                    sourceId: String(sourceId || ''),
+                    targetId: String(targetId || ''),
+                    maxDepth: typeof maxDepth === 'number' ? Math.max(1, Math.floor(maxDepth)) : undefined,
+                });
+                if (!res.ok) {
+                    consecutiveFailures++;
+                    if (consecutiveFailures >= circuitThreshold) {
+                        circuitState = 'open';
+                        circuitOpenedAt = new Date().toISOString();
+                    }
+                    throw new Error('graphdb_http_request_failed:' + res.status);
+                }
+                consecutiveFailures = 0;
+                const payload = await res.json();
+                const pathResult = payload?.pathResult ?? payload?.result ?? payload;
+                if (!pathResult || typeof pathResult !== 'object') {
+                    return { path: [], length: 0, edges: [], found: false };
+                }
+                return {
+                    path: Array.isArray(pathResult.path) ? pathResult.path.map((item) => String(item || '')) : [],
+                    length: Math.max(0, Math.floor(Number(pathResult.length || 0))),
+                    edges: Array.isArray(pathResult.edges)
+                        ? pathResult.edges.map((item) => ({
+                            from: String(item?.from || ''),
+                            to: String(item?.to || ''),
+                            relation: item?.relation ? String(item.relation) : undefined,
+                        }))
+                        : [],
+                    found: pathResult.found === true,
+                };
+            },
+            getDiagnostics: () => ({
+                storeType: 'graphdb',
+                exists: okCount > 0,
+                loaded: okCount > 0,
+                location: snapUrl,
+                capabilityMode: 'ops_capable',
+                supportedReadOperations: ['load_snapshot', 'get_node', 'query_nodes', 'query_edges', 'find_path'],
+                supportedWriteOperations: ['save_snapshot'],
+                connector: {
+                    healthStatus: circuitState === 'open' ? 'unavailable' : failCount > 0 ? 'degraded' : 'ready',
+                    circuitState,
+                    requestCount: reqCount,
+                    successCount: okCount,
+                    failureCount: failCount,
+                    consecutiveFailures,
+                    shortCircuitCount,
+                    circuitOpenedAt: circuitOpenedAt || undefined,
+                    lastRequestId: lastReqId,
+                    lastErrorCode: circuitState === 'open' ? 'circuit_open' : (lastErrCode || undefined),
+                    lastStatusCode: lastStatusCode > 0 ? lastStatusCode : undefined,
+                },
+            }),
+        };
+    }
+    return null;
+}
+function createKnowledgeGraphStore(o) {
+    const backend = normalizeKnowledgeGraphStoreBackend(o.backend);
+    const filePath = o.filePath ?? '/tmp/notemd-kg-default.json';
+    // Support both old (flat) and new (nested) parameter styles
+    const graphdbAdapter = o.graphdb?.adapter ?? o.graphDbAdapter ?? null;
+    const graphdbOperationMode = (o.graphdb?.operationMode ?? o.graphDbOperationMode ?? 'snapshot');
+    const graphdbFallbackEnabled = (o.graphdb?.fallbackEnabled ?? o.graphDbFallbackEnabled ?? true);
+    if (backend === 'memory') {
+        // In-memory store for testing
+        let memorySnapshot = null;
+        return {
+            loadSnapshot: async () => memorySnapshot,
+            saveSnapshot: async (snapshot) => { memorySnapshot = snapshot; },
+            getDiagnostics: () => ({
+                storeType: 'memory',
+                exists: memorySnapshot !== null,
+                loaded: memorySnapshot !== null,
+            }),
+            close: () => {
+                memorySnapshot = null;
+            },
+        };
+    }
+    if (backend === 'graphdb') {
+        if (graphdbAdapter && typeof graphdbAdapter.loadSnapshot === 'function') {
+            const a = graphdbAdapter;
+            const opsCapable = hasOpsCapablePath(a);
+            const requestMode = normalizeGraphDbStoreOperationMode(graphdbOperationMode);
+            const opsState = { probed: false, opsReadUsed: false, opsWriteUsed: false, lastProbeResult: null };
+            const queryOpsState = {
+                nodeOpsReadCount: 0,
+                nodeFallbackCount: 0,
+                nodesOpsReadCount: 0,
+                nodesFallbackCount: 0,
+                edgesOpsReadCount: 0,
+                edgesFallbackCount: 0,
+                pathOpsReadCount: 0,
+                pathFallbackCount: 0,
+            };
+            const resolveOpsPath = async () => {
+                if (!opsCapable || requestMode !== 'ops_preferred')
+                    return false;
+                if (opsState.probed)
+                    return true;
+                if (typeof a.probeSnapshotMetadata === 'function') {
+                    try {
+                        opsState.lastProbeResult = await a.probeSnapshotMetadata();
+                        opsState.probed = true;
+                        return true;
+                    }
+                    catch { /* probe failed, fall through to snapshot */ }
+                }
+                // No probe method: try ops path anyway, let it fail gracefully
+                return true; // allow ops attempt — downgrade on failure
+            };
+            const loadSnapshotThroughAdapter = async () => {
+                if (opsCapable && requestMode === 'ops_preferred') {
+                    if (typeof a.probeSnapshotMetadata === 'function' && !opsState.probed) {
+                        try {
+                            opsState.lastProbeResult = await a.probeSnapshotMetadata();
+                            opsState.probed = true;
+                        }
+                        catch { /* fall through */ }
+                    }
+                    if ((opsState.probed || typeof a.probeSnapshotMetadata !== 'function') && typeof a.loadSnapshotByOps === 'function') {
+                        try {
+                            const result = await a.loadSnapshotByOps();
+                            opsState.probed = true;
+                            opsState.opsReadUsed = true;
+                            return result;
+                        }
+                        catch {
+                            // Downgrade: ops read failed, fall back to snapshot read
+                        }
+                    }
+                }
+                return a.loadSnapshot();
+            };
+            const saveSnapshotThroughAdapter = async (snapshot) => {
+                if (await resolveOpsPath() && typeof a.saveSnapshotByOps === 'function') {
+                    try {
+                        await a.saveSnapshotByOps(snapshot);
+                        opsState.opsWriteUsed = true;
+                        if (typeof a.probeSnapshotMetadata === 'function') {
+                            try {
+                                opsState.lastProbeResult = await a.probeSnapshotMetadata();
+                            }
+                            catch { /* ignore */ }
+                        }
+                        return;
+                    }
+                    catch {
+                        // Downgrade: ops write failed, fall back to snapshot write
+                    }
+                }
+                await a.saveSnapshot(snapshot);
+                if (typeof a.probeSnapshotMetadata === 'function') {
+                    try {
+                        opsState.lastProbeResult = await a.probeSnapshotMetadata();
+                        opsState.probed = true;
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+            };
+            const resolveOpsCapabilities = () => {
+                const caps = a.getCapabilities?.() ?? {};
+                const supportedReadOperations = Array.isArray(caps.supportedReadOperations)
+                    ? caps.supportedReadOperations
+                    : [];
+                const supportedWriteOperations = Array.isArray(caps.supportedWriteOperations)
+                    ? caps.supportedWriteOperations
+                    : [];
+                const nodeQuerySupported = caps.nodeQuerySupported === true || typeof a.getNodeByOps === 'function';
+                const edgeQuerySupported = caps.edgeQuerySupported === true || typeof a.queryEdgesByOps === 'function';
+                const pathQuerySupported = caps.pathQuerySupported === true || typeof a.findPathByOps === 'function';
+                const snapshotSupported = caps.snapshotSupported !== false;
+                const writeSupported = caps.writeSupported !== false;
+                const serverSideQuery = caps.serverSideQuery === true
+                    || nodeQuerySupported
+                    || edgeQuerySupported
+                    || pathQuerySupported;
+                return {
+                    snapshotSupported,
+                    nodeQuerySupported,
+                    edgeQuerySupported,
+                    pathQuerySupported,
+                    writeSupported,
+                    serverSideQuery,
+                    mode: String(caps.mode || (opsCapable ? 'ops_capable' : 'snapshot_only')),
+                    supportedReadOperations,
+                    supportedWriteOperations,
+                };
+            };
+            const querySnapshotForNode = async (atomId) => {
+                const snapshot = await loadSnapshotThroughAdapter();
+                if (!snapshot)
+                    return null;
+                return snapshot.atoms.find((atom) => atom.id === atomId || atom.stableKey === atomId) ?? null;
+            };
+            const querySnapshotForNodes = async (filter) => {
+                const snapshot = await loadSnapshotThroughAdapter();
+                if (!snapshot)
+                    return [];
+                return filterNodesFromSnapshot(snapshot, filter);
+            };
+            const querySnapshotForEdges = async (filter) => {
+                const snapshot = await loadSnapshotThroughAdapter();
+                if (!snapshot)
+                    return [];
+                return filterEdgesFromSnapshot(snapshot, filter);
+            };
+            const querySnapshotForPath = async (sourceId, targetId, maxDepth = 10) => {
+                const snapshot = await loadSnapshotThroughAdapter();
+                if (!snapshot)
+                    return { path: [], length: 0, edges: [], found: false };
+                return findPathInSnapshot(snapshot, sourceId, targetId, maxDepth);
+            };
+            return {
+                loadSnapshot: async () => loadSnapshotThroughAdapter(),
+                saveSnapshot: async (snapshot) => saveSnapshotThroughAdapter(snapshot),
+                close: () => {
+                    try {
+                        a.close?.();
+                    }
+                    catch {
+                    }
+                },
+                getDiagnostics: () => {
+                    const diag = a.getDiagnostics?.() ?? {};
+                    const caps = resolveOpsCapabilities();
+                    const totalQueryOpsReadCount = queryOpsState.nodeOpsReadCount
+                        + queryOpsState.nodesOpsReadCount
+                        + queryOpsState.edgesOpsReadCount
+                        + queryOpsState.pathOpsReadCount;
+                    const totalQueryFallbackCount = queryOpsState.nodeFallbackCount
+                        + queryOpsState.nodesFallbackCount
+                        + queryOpsState.edgesFallbackCount
+                        + queryOpsState.pathFallbackCount;
+                    return {
+                        exists: diag.exists ?? false,
+                        loaded: diag.loaded ?? false,
+                        backendReady: true,
+                        usingFallback: false,
+                        adapterId: a.id,
+                        ...diag,
+                        storeType: 'graphdb',
+                        graphDbOperationMode: normalizeGraphDbStoreOperationMode(graphdbOperationMode),
+                        fallbackEnabled: graphdbFallbackEnabled,
+                        graphDbAdapterCapabilityMode: diag.capabilityMode ?? caps.mode ?? (opsCapable ? 'ops_capable' : 'snapshot_only'),
+                        graphDbReadPath: opsState.opsReadUsed ? 'ops' : diag.lastReadPath ?? 'snapshot',
+                        graphDbWritePath: opsState.opsWriteUsed ? 'ops' : diag.lastWritePath ?? 'snapshot',
+                        graphDbSupportedReadOperations: diag.supportedReadOperations ?? caps.supportedReadOperations,
+                        graphDbSupportedWriteOperations: diag.supportedWriteOperations ?? caps.supportedWriteOperations,
+                        graphDbLastSnapshotMetadata: opsState.lastProbeResult ?? diag.lastSnapshotMetadata,
+                        graphDbQueryPath: totalQueryOpsReadCount > 0 ? 'ops' : 'snapshot',
+                        graphDbQueryOpsReadCount: totalQueryOpsReadCount,
+                        graphDbQueryFallbackCount: totalQueryFallbackCount,
+                        graphDbNodeQuerySupported: caps.nodeQuerySupported,
+                        graphDbEdgeQuerySupported: caps.edgeQuerySupported,
+                        graphDbPathQuerySupported: caps.pathQuerySupported,
+                    };
+                },
+                getCapabilities: () => resolveOpsCapabilities(),
+                getNode: async (atomId) => {
+                    if (requestMode === 'ops_preferred' && typeof a.getNodeByOps === 'function') {
+                        try {
+                            queryOpsState.nodeOpsReadCount += 1;
+                            return await a.getNodeByOps(atomId);
+                        }
+                        catch {
+                            queryOpsState.nodeFallbackCount += 1;
+                        }
+                    }
+                    return querySnapshotForNode(atomId);
+                },
+                queryNodes: async (filter) => {
+                    if (requestMode === 'ops_preferred' && typeof a.queryNodesByOps === 'function') {
+                        try {
+                            queryOpsState.nodesOpsReadCount += 1;
+                            return await a.queryNodesByOps(filter);
+                        }
+                        catch {
+                            queryOpsState.nodesFallbackCount += 1;
+                        }
+                    }
+                    return querySnapshotForNodes(filter);
+                },
+                queryEdges: async (filter) => {
+                    if (requestMode === 'ops_preferred' && typeof a.queryEdgesByOps === 'function') {
+                        try {
+                            queryOpsState.edgesOpsReadCount += 1;
+                            return await a.queryEdgesByOps(filter);
+                        }
+                        catch {
+                            queryOpsState.edgesFallbackCount += 1;
+                        }
+                    }
+                    return querySnapshotForEdges(filter);
+                },
+                findPath: async (sourceId, targetId, maxDepth = 10) => {
+                    if (requestMode === 'ops_preferred' && typeof a.findPathByOps === 'function') {
+                        try {
+                            queryOpsState.pathOpsReadCount += 1;
+                            return await a.findPathByOps(sourceId, targetId, maxDepth);
+                        }
+                        catch {
+                            queryOpsState.pathFallbackCount += 1;
+                        }
+                    }
+                    return querySnapshotForPath(sourceId, targetId, maxDepth);
+                },
+            };
+        }
+        // Fail closed when fallback is disabled and adapter is unavailable
+        if (!graphdbFallbackEnabled) {
+            return {
+                loadSnapshot: async () => { throw new Error('graphdb_adapter_unavailable_no_fallback'); },
+                saveSnapshot: async () => { throw new Error('graphdb_adapter_unavailable_no_fallback'); },
+                close: () => { },
+                getDiagnostics: () => ({
+                    storeType: 'graphdb',
+                    exists: false, loaded: false,
+                    backendReady: false,
+                    usingFallback: false,
+                    fallbackEnabled: false,
+                    lastError: 'graphdb_adapter_unavailable_no_fallback',
+                    graphDbOperationMode: normalizeGraphDbStoreOperationMode(graphdbOperationMode),
+                    graphDbAdapterCapabilityMode: 'unknown',
+                    graphDbReadPath: 'fallback',
+                    graphDbWritePath: 'fallback',
+                }),
+            };
+        }
+        // Fall back to file store
+        const fallback = new FileBackedKnowledgeGraphStore({ filePath });
+        return {
+            loadSnapshot: () => fallback.loadSnapshot(),
+            saveSnapshot: (snapshot) => fallback.saveSnapshot(snapshot),
+            close: () => {
+                try {
+                    graphdbAdapter?.close?.();
+                }
+                catch {
+                }
+            },
+            getDiagnostics: () => ({
+                ...fallback.getDiagnostics(),
+                storeType: 'graphdb',
+                backendReady: false,
+                usingFallback: true,
+                fallbackEnabled: true,
+                fallbackStoreType: 'file',
+                graphDbOperationMode: 'snapshot_only',
+                graphDbAdapterCapabilityMode: 'unknown',
+                graphDbReadPath: 'fallback',
+                graphDbWritePath: 'fallback',
+            }),
+        };
+    }
+    return new FileBackedKnowledgeGraphStore({ filePath });
+}