noteconnection 1.7.0 → 1.9.0

package/dist/src/learning/store.test.js

@@ -0,0 +1,1425 @@
+"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 });
+const fs = __importStar(require("fs"));
+const http = __importStar(require("http"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const store_1 = require("./store");
+function createSnapshot(seed) {
+    return {
+        schemaVersion: 1,
+        savedAt: new Date('2026-01-01T00:00:00.000Z').toISOString(),
+        idCounter: 1,
+        atoms: [],
+        evidenceSpans: [],
+        relationEdges: [],
+        temporalEdges: [],
+        documents: [],
+        activeStableKeyToAtomId: [],
+        activeAtomIds: [],
+        learnerStates: [],
+        tutorTraces: [],
+        ingestLatencyHistoryMs: [],
+        recomputeLatencyHistoryMs: [],
+        queryLatencyHistoryMs: [],
+        latestIngestSummary: null,
+        sessionActionTelemetry: {
+            executionCount: 0,
+            analyzedAnswerCount: 0,
+            inferredMasteryUpdateCount: 0,
+            explicitMasteryUpdateCount: 0,
+            memoryPersistedCount: 0,
+            memoryPromotionAppliedCount: 0,
+            memoryPromotionCount: 0,
+            verifiedTutorCount: 0,
+            pendingVerificationCount: 0,
+            outcomeCounts: {
+                correct: 0,
+                partial: 0,
+                incorrect: 0,
+                skipped: 0,
+            },
+        },
+        sessionExecutionHistory: [],
+        userMemory: {
+            [seed]: {
+                session: [],
+                unit: [],
+                long_term: [],
+            },
+        },
+        relationEdgeSignatures: [],
+    };
+}
+function createAtom(id, title, content) {
+    return {
+        id,
+        stableKey: `${id}_stable`,
+        documentId: 'doc_ops',
+        sourcePath: '/ops/doc.md',
+        title,
+        content: content || `${title} content`,
+        representationType: 'text',
+        keywords: [title.toLowerCase()],
+        evidenceSpanIds: [],
+        createdAt: new Date('2026-01-01T00:00:00.000Z').toISOString(),
+        updatedAt: new Date('2026-01-01T00:00:00.000Z').toISOString(),
+        metadata: {
+            sectionPath: ['root'],
+            version: 1,
+            sourceHash: `${id}_hash`,
+            language: 'en',
+        },
+    };
+}
+function createRelation(id, sourceAtomId, targetAtomId, relationKind = 'sequence') {
+    return {
+        id,
+        sourceAtomId,
+        targetAtomId,
+        relationKind,
+        provenance: 'fact',
+        confidence: 0.95,
+        evidenceSpanIds: [],
+        temporal: {
+            validFrom: new Date('2026-01-01T00:00:00.000Z').toISOString(),
+        },
+    };
+}
+function buildProbeMetadataFromSnapshot(snapshot) {
+    if (!snapshot) {
+        return null;
+    }
+    return {
+        schemaVersion: snapshot.schemaVersion,
+        savedAt: snapshot.savedAt,
+        atomCount: snapshot.atoms.length,
+        relationEdgeCount: snapshot.relationEdges.length,
+        temporalEdgeCount: snapshot.temporalEdges.length,
+        documentCount: snapshot.documents.length,
+    };
+}
+async function startMockGraphDbSnapshotServer() {
+    let persistedSnapshot = null;
+    const requests = [];
+    const server = http.createServer((req, res) => {
+        const method = String(req.method || 'GET').toUpperCase();
+        const requestPath = String(req.url || '');
+        let rawBody = '';
+        req.setEncoding('utf8');
+        req.on('data', (chunk) => {
+            rawBody += chunk;
+        });
+        req.on('end', () => {
+            let parsedBody = null;
+            if (rawBody.trim().length > 0) {
+                try {
+                    parsedBody = JSON.parse(rawBody);
+                }
+                catch {
+                    parsedBody = rawBody;
+                }
+            }
+            requests.push({
+                method,
+                path: requestPath,
+                body: parsedBody,
+            });
+            const nodeMatch = requestPath.match(/^\/graphdb\/ops\/node\/(.+)$/);
+            if (nodeMatch && method === 'GET') {
+                if (!persistedSnapshot) {
+                    res.statusCode = 404;
+                    res.setHeader('X-Request-Id', `graphdb-mock-${requests.length}`);
+                    res.setHeader('X-Error-Code', 'snapshot_not_found');
+                    res.end(JSON.stringify({ error: 'snapshot_not_found' }));
+                    return;
+                }
+                const rawId = decodeURIComponent(nodeMatch[1] || '').trim();
+                const node = persistedSnapshot.atoms.find((atom) => atom.id === rawId || atom.stableKey === rawId) ?? null;
+                if (!node) {
+                    res.statusCode = 404;
+                    res.setHeader('X-Request-Id', `graphdb-mock-${requests.length}`);
+                    res.setHeader('X-Error-Code', 'node_not_found');
+                    res.end(JSON.stringify({ error: 'node_not_found' }));
+                    return;
+                }
+                res.statusCode = 200;
+                res.setHeader('Content-Type', 'application/json');
+                res.setHeader('X-Request-Id', `graphdb-mock-${requests.length}`);
+                res.end(JSON.stringify({ success: true, node }));
+                return;
+            }
+            if (requestPath === '/graphdb/ops/nodes' && method === 'POST') {
+                if (!persistedSnapshot) {
+                    res.statusCode = 404;
+                    res.setHeader('X-Request-Id', `graphdb-mock-${requests.length}`);
+                    res.setHeader('X-Error-Code', 'snapshot_not_found');
+                    res.end(JSON.stringify({ error: 'snapshot_not_found' }));
+                    return;
+                }
+                const filter = (parsedBody
+                    && typeof parsedBody === 'object'
+                    && !Array.isArray(parsedBody)
+                    && parsedBody.filter
+                    && typeof parsedBody.filter === 'object') ? parsedBody.filter : {};
+                let nodes = persistedSnapshot.atoms;
+                if (Array.isArray(filter.nodeIds) && filter.nodeIds.length > 0) {
+                    const idSet = new Set(filter.nodeIds.map((item) => String(item || '')));
+                    nodes = nodes.filter((atom) => idSet.has(atom.id) || idSet.has(atom.stableKey ?? ''));
+                }
+                if (String(filter.stableKey || '').trim()) {
+                    nodes = nodes.filter((atom) => atom.stableKey === String(filter.stableKey));
+                }
+                if (Number.isFinite(Number(filter.limit)) && Number(filter.limit) > 0) {
+                    nodes = nodes.slice(0, Math.max(1, Math.floor(Number(filter.limit))));
+                }
+                res.statusCode = 200;
+                res.setHeader('Content-Type', 'application/json');
+                res.setHeader('X-Request-Id', `graphdb-mock-${requests.length}`);
+                res.end(JSON.stringify({ success: true, nodes }));
+                return;
+            }
+            if (requestPath === '/graphdb/ops/edges' && method === 'POST') {
+                if (!persistedSnapshot) {
+                    res.statusCode = 404;
+                    res.setHeader('X-Request-Id', `graphdb-mock-${requests.length}`);
+                    res.setHeader('X-Error-Code', 'snapshot_not_found');
+                    res.end(JSON.stringify({ error: 'snapshot_not_found' }));
+                    return;
+                }
+                const filter = (parsedBody
+                    && typeof parsedBody === 'object'
+                    && !Array.isArray(parsedBody)
+                    && parsedBody.filter
+                    && typeof parsedBody.filter === 'object') ? parsedBody.filter : {};
+                let edges = persistedSnapshot.relationEdges;
+                if (String(filter.fromNodeId || '').trim()) {
+                    edges = edges.filter((edge) => edge.sourceAtomId === String(filter.fromNodeId));
+                }
+                if (String(filter.toNodeId || '').trim()) {
+                    edges = edges.filter((edge) => edge.targetAtomId === String(filter.toNodeId));
+                }
+                if (String(filter.relationKind || '').trim()) {
+                    edges = edges.filter((edge) => edge.relationKind === String(filter.relationKind));
+                }
+                if (Number.isFinite(Number(filter.limit)) && Number(filter.limit) > 0) {
+                    edges = edges.slice(0, Math.max(1, Math.floor(Number(filter.limit))));
+                }
+                res.statusCode = 200;
+                res.setHeader('Content-Type', 'application/json');
+                res.setHeader('X-Request-Id', `graphdb-mock-${requests.length}`);
+                res.end(JSON.stringify({ success: true, edges }));
+                return;
+            }
+            if (requestPath === '/graphdb/ops/path' && method === 'POST') {
+                if (!persistedSnapshot) {
+                    res.statusCode = 404;
+                    res.setHeader('X-Request-Id', `graphdb-mock-${requests.length}`);
+                    res.setHeader('X-Error-Code', 'snapshot_not_found');
+                    res.end(JSON.stringify({ error: 'snapshot_not_found' }));
+                    return;
+                }
+                const sourceId = String(parsedBody?.sourceId || '').trim();
+                const targetId = String(parsedBody?.targetId || '').trim();
+                const maxDepth = Number.isFinite(Number(parsedBody?.maxDepth))
+                    ? Math.max(1, Math.floor(Number(parsedBody?.maxDepth)))
+                    : 10;
+                const adjacency = new Map();
+                for (const edge of persistedSnapshot.relationEdges) {
+                    if (!adjacency.has(edge.sourceAtomId))
+                        adjacency.set(edge.sourceAtomId, []);
+                    adjacency.get(edge.sourceAtomId).push({
+                        to: edge.targetAtomId,
+                        relation: edge.relationKind,
+                    });
+                }
+                const visited = new Set();
+                const queue = [
+                    { nodeId: sourceId, path: [sourceId], edges: [] },
+                ];
+                visited.add(sourceId);
+                let pathResult = { path: [], length: 0, edges: [], found: false };
+                while (queue.length > 0) {
+                    const current = queue.shift();
+                    if (current.path.length > maxDepth)
+                        continue;
+                    if (current.nodeId === targetId) {
+                        pathResult = {
+                            path: current.path,
+                            length: current.path.length - 1,
+                            edges: current.edges,
+                            found: true,
+                        };
+                        break;
+                    }
+                    const neighbors = adjacency.get(current.nodeId) ?? [];
+                    for (const neighbor of neighbors) {
+                        if (!visited.has(neighbor.to)) {
+                            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 }],
+                            });
+                        }
+                    }
+                }
+                res.statusCode = 200;
+                res.setHeader('Content-Type', 'application/json');
+                res.setHeader('X-Request-Id', `graphdb-mock-${requests.length}`);
+                res.end(JSON.stringify({ success: true, pathResult }));
+                return;
+            }
+            if (requestPath !== '/graphdb/snapshot') {
+                res.statusCode = 404;
+                res.setHeader('X-Request-Id', `graphdb-mock-${requests.length}`);
+                res.setHeader('X-Error-Code', 'not_found');
+                res.end(JSON.stringify({ error: 'not_found' }));
+                return;
+            }
+            if (method === 'GET') {
+                if (!persistedSnapshot) {
+                    res.statusCode = 404;
+                    res.setHeader('X-Request-Id', `graphdb-mock-${requests.length}`);
+                    res.setHeader('X-Error-Code', 'snapshot_not_found');
+                    res.end(JSON.stringify({ error: 'snapshot_not_found' }));
+                    return;
+                }
+                res.statusCode = 200;
+                res.setHeader('Content-Type', 'application/json');
+                res.setHeader('X-Request-Id', `graphdb-mock-${requests.length}`);
+                res.end(JSON.stringify({ success: true, snapshot: persistedSnapshot }));
+                return;
+            }
+            if (method === 'POST') {
+                const nextSnapshot = (parsedBody
+                    && typeof parsedBody === 'object'
+                    && !Array.isArray(parsedBody)
+                    && Object.prototype.hasOwnProperty.call(parsedBody, 'snapshot'))
+                    ? parsedBody.snapshot
+                    : null;
+                if (!nextSnapshot) {
+                    res.statusCode = 400;
+                    res.setHeader('X-Request-Id', `graphdb-mock-${requests.length}`);
+                    res.setHeader('X-Error-Code', 'snapshot_required');
+                    res.end(JSON.stringify({ error: 'snapshot_required' }));
+                    return;
+                }
+                persistedSnapshot = nextSnapshot;
+                res.statusCode = 200;
+                res.setHeader('Content-Type', 'application/json');
+                res.setHeader('X-Request-Id', `graphdb-mock-${requests.length}`);
+                res.end(JSON.stringify({ success: true }));
+                return;
+            }
+            res.statusCode = 405;
+            res.setHeader('X-Request-Id', `graphdb-mock-${requests.length}`);
+            res.setHeader('X-Error-Code', 'method_not_allowed');
+            res.end(JSON.stringify({ error: 'method_not_allowed' }));
+        });
+    });
+    const port = await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (!address || typeof address !== 'object') {
+                reject(new Error('Failed to allocate mock graphdb port.'));
+                return;
+            }
+            resolve(address.port);
+        });
+    });
+    return {
+        endpoint: `http://127.0.0.1:${port}/graphdb`,
+        requests,
+        close: () => new Promise((resolve, reject) => {
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        }),
+    };
+}
+describe('Knowledge graph store backend factory', () => {
+    test('memory backend stores and restores snapshots in-process', async () => {
+        const store = (0, store_1.createKnowledgeGraphStore)({
+            backend: 'memory',
+            filePath: '/tmp/unused.v1.json',
+        });
+        expect(store.getDiagnostics().storeType).toBe('memory');
+        expect(await store.loadSnapshot()).toBeNull();
+        const snapshot = createSnapshot('memory_user');
+        await store.saveSnapshot(snapshot);
+        const restored = await store.loadSnapshot();
+        expect(restored).toEqual(snapshot);
+        expect(store.getDiagnostics().exists).toBe(true);
+        expect(store.getDiagnostics().loaded).toBe(true);
+    });
+    test('unknown backend value is normalized to file backend', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-test-'));
+        const filePath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.v1.json');
+        try {
+            expect((0, store_1.normalizeKnowledgeGraphStoreBackend)('unknown-backend')).toBe('file');
+            const store = (0, store_1.createKnowledgeGraphStore)({
+                backend: 'unknown-backend',
+                filePath,
+            });
+            const snapshot = createSnapshot('file_user');
+            await store.saveSnapshot(snapshot);
+            const restored = await store.loadSnapshot();
+            expect(restored).toEqual(snapshot);
+            const diagnostics = store.getDiagnostics();
+            expect(diagnostics.storeType).toBe('file');
+            expect(diagnostics.exists).toBe(true);
+            expect(fs.existsSync(filePath)).toBe(true);
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('refreshes the in-process snapshot cache after a save', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-cache-coherence-'));
+        const filePath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.v1.json');
+        try {
+            const store = (0, store_1.createFileBackedKnowledgeGraphStore)({ filePath });
+            const first = createSnapshot('cache_first');
+            first.atoms = [createAtom('atom_first', 'First')];
+            const second = createSnapshot('cache_second');
+            second.atoms = [createAtom('atom_second', 'Second')];
+            await store.saveSnapshot(first);
+            expect(await store.getNode('atom_first')).toEqual(first.atoms[0]);
+            await store.saveSnapshot(second);
+            expect(await store.getNode('atom_first')).toBeNull();
+            expect(await store.getNode('atom_second')).toEqual(second.atoms[0]);
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('uses a unique sibling temporary path for each save', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-atomic-save-'));
+        const filePath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.v1.json');
+        const renameSpy = jest.spyOn(fs.promises, 'rename');
+        try {
+            const store = (0, store_1.createKnowledgeGraphStore)({ backend: 'file', filePath });
+            await store.saveSnapshot(createSnapshot('atomic_first'));
+            await store.saveSnapshot(createSnapshot('atomic_second'));
+            const temporaryPaths = renameSpy.mock.calls
+                .map(([sourcePath]) => String(sourcePath));
+            expect(new Set(temporaryPaths).size).toBe(2);
+            expect(fs.existsSync(filePath)).toBe(true);
+            expect(fs.readdirSync(path.dirname(filePath)).filter((name) => name.includes('.tmp'))).toHaveLength(0);
+        }
+        finally {
+            renameSpy.mockRestore();
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('keeps the target parseable when saves overlap', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-concurrent-save-'));
+        const filePath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.v1.json');
+        try {
+            const store = (0, store_1.createFileBackedKnowledgeGraphStore)({ filePath });
+            const first = createSnapshot('concurrent_first');
+            first.atoms = [createAtom('atom_concurrent_first', 'Concurrent First')];
+            const second = createSnapshot('concurrent_second');
+            second.atoms = [createAtom('atom_concurrent_second', 'Concurrent Second')];
+            await Promise.all([
+                store.saveSnapshot(first),
+                store.saveSnapshot(second),
+            ]);
+            const persisted = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+            expect(['atom_concurrent_first', 'atom_concurrent_second']).toContain(persisted.atoms[0]?.id);
+            expect(fs.readdirSync(path.dirname(filePath)).filter((name) => name.endsWith('.tmp'))).toHaveLength(0);
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('normalizes graphdb adapter provider aliases', () => {
+        expect((0, store_1.normalizeGraphDbSnapshotAdapterProvider)('file')).toBe('file');
+        expect((0, store_1.normalizeGraphDbSnapshotAdapterProvider)('local-file')).toBe('file');
+        expect((0, store_1.normalizeGraphDbSnapshotAdapterProvider)('external_http')).toBe('http');
+        expect((0, store_1.normalizeGraphDbSnapshotAdapterProvider)('remote-http')).toBe('http');
+        expect((0, store_1.normalizeGraphDbSnapshotAdapterProvider)('service')).toBe('http');
+        expect((0, store_1.normalizeGraphDbSnapshotAdapterProvider)('sqlite')).toBe('sqlite');
+        expect((0, store_1.normalizeGraphDbSnapshotAdapterProvider)('embedded_sqlite')).toBe('sqlite');
+        expect((0, store_1.normalizeGraphDbSnapshotAdapterProvider)('none')).toBe('none');
+        expect((0, store_1.normalizeGraphDbSnapshotAdapterProvider)('disabled')).toBe('none');
+        expect((0, store_1.normalizeGraphDbSnapshotAdapterProvider)('fallback_only')).toBe('none');
+        expect((0, store_1.normalizeGraphDbSnapshotAdapterProvider)('unknown')).toBe('file');
+    });
+    test('normalizes cross-platform storage provider kinds without conflating http and projection', () => {
+        expect((0, store_1.normalizeStorageProviderKind)('sqlite')).toBe('sqlite');
+        expect((0, store_1.normalizeStorageProviderKind)('embedded-sqlite')).toBe('sqlite');
+        expect((0, store_1.normalizeStorageProviderKind)('file')).toBe('file');
+        expect((0, store_1.normalizeStorageProviderKind)('external_http')).toBe('remote');
+        expect((0, store_1.normalizeStorageProviderKind)('remote')).toBe('remote');
+        expect((0, store_1.normalizeStorageProviderKind)('mobile_projection')).toBe('projection');
+        expect((0, store_1.normalizeStorageProviderKind)('unknown')).toBeUndefined();
+    });
+    test('reports file resolution when a requested sqlite graph adapter is unavailable', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-provider-resolution-'));
+        const filePath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.v1.json');
+        try {
+            const store = (0, store_1.createKnowledgeGraphStore)({
+                backend: 'graphdb',
+                filePath,
+                graphdb: { adapter: null },
+                graphDbRequestedProvider: 'sqlite',
+                graphDbFallbackEnabled: true,
+            });
+            expect(store.getDiagnostics()).toEqual(expect.objectContaining({
+                requestedProvider: 'sqlite',
+                resolvedProvider: 'file',
+                fallbackReason: 'sqlite_runtime_unavailable',
+                storageEngine: 'file',
+            }));
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('normalizes graphdb operation mode aliases', () => {
+        expect((0, store_1.normalizeGraphDbStoreOperationMode)('snapshot')).toBe('snapshot_only');
+        expect((0, store_1.normalizeGraphDbStoreOperationMode)('snapshot_only')).toBe('snapshot_only');
+        expect((0, store_1.normalizeGraphDbStoreOperationMode)('ops')).toBe('ops_preferred');
+        expect((0, store_1.normalizeGraphDbStoreOperationMode)('ops_preferred')).toBe('ops_preferred');
+        expect((0, store_1.normalizeGraphDbStoreOperationMode)('operations')).toBe('ops_preferred');
+        expect((0, store_1.normalizeGraphDbStoreOperationMode)('unknown')).toBe('snapshot_only');
+    });
+    test('graphdb adapter factory supports provider-based rollout selection', async () => {
+        const disabledAdapter = (0, store_1.createGraphDbSnapshotAdapter)({
+            provider: 'none',
+            filePath: '/tmp/unused.graphdb.v1.json',
+        });
+        expect(disabledAdapter).toBeNull();
+        const fileAdapter = (0, store_1.createGraphDbSnapshotAdapter)({
+            provider: 'file',
+            filePath: '/tmp/knowledge_graph_store.graphdb.v1.json',
+            fileAdapterId: 'file-adapter-from-factory',
+        });
+        expect(fileAdapter?.id).toBe('file-adapter-from-factory');
+        const mockServer = await startMockGraphDbSnapshotServer();
+        try {
+            const httpAdapter = (0, store_1.createGraphDbSnapshotAdapter)({
+                provider: 'external_http',
+                filePath: '/tmp/unused.graphdb.v1.json',
+                adapterId: 'http-adapter-from-factory',
+                httpEndpoint: mockServer.endpoint,
+                httpTimeoutMs: 800,
+                httpMaxRetries: 0,
+            });
+            expect(httpAdapter?.id).toBe('http-adapter-from-factory');
+        }
+        finally {
+            await mockServer.close();
+        }
+    });
+    test('graphdb backend falls back to file store when adapter is not configured', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-graphdb-fallback-'));
+        const filePath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.v1.json');
+        try {
+            expect((0, store_1.normalizeKnowledgeGraphStoreBackend)('graphdb')).toBe('graphdb');
+            const store = (0, store_1.createKnowledgeGraphStore)({
+                backend: 'graphdb',
+                filePath,
+            });
+            const snapshot = createSnapshot('graphdb_fallback_user');
+            await store.saveSnapshot(snapshot);
+            const restored = await store.loadSnapshot();
+            expect(restored).toEqual(snapshot);
+            expect(fs.existsSync(filePath)).toBe(true);
+            const diagnostics = store.getDiagnostics();
+            expect(diagnostics.storeType).toBe('graphdb');
+            expect(diagnostics.backendReady).toBe(false);
+            expect(diagnostics.usingFallback).toBe(true);
+            expect(diagnostics.fallbackStoreType).toBe('file');
+            expect(diagnostics.graphDbOperationMode).toBe('snapshot_only');
+            expect(diagnostics.graphDbAdapterCapabilityMode).toBe('unknown');
+            expect(diagnostics.graphDbReadPath).toBe('fallback');
+            expect(diagnostics.graphDbWritePath).toBe('fallback');
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('graphdb backend uses configured adapter and bypasses file fallback', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-graphdb-adapter-'));
+        const filePath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.v1.json');
+        let persisted = null;
+        const adapter = {
+            id: 'mock-graphdb',
+            async loadSnapshot() {
+                return persisted;
+            },
+            async saveSnapshot(snapshot) {
+                persisted = snapshot;
+            },
+            getDiagnostics() {
+                return {
+                    location: 'graphdb://mock',
+                    exists: persisted !== null,
+                    loaded: true,
+                };
+            },
+        };
+        try {
+            const store = (0, store_1.createKnowledgeGraphStore)({
+                backend: 'graphdb',
+                filePath,
+                graphdb: { adapter },
+            });
+            const snapshot = createSnapshot('graphdb_adapter_user');
+            await store.saveSnapshot(snapshot);
+            const restored = await store.loadSnapshot();
+            expect(restored).toEqual(snapshot);
+            expect(fs.existsSync(filePath)).toBe(false);
+            const diagnostics = store.getDiagnostics();
+            expect(diagnostics.storeType).toBe('graphdb');
+            expect(diagnostics.location).toBe('graphdb://mock');
+            expect(diagnostics.backendReady).toBe(true);
+            expect(diagnostics.usingFallback).toBe(false);
+            expect(diagnostics.adapterId).toBe('mock-graphdb');
+            expect(diagnostics.graphDbOperationMode).toBe('snapshot_only');
+            expect(diagnostics.graphDbAdapterCapabilityMode).toBe('snapshot_only');
+            expect(diagnostics.graphDbReadPath).toBe('snapshot');
+            expect(diagnostics.graphDbWritePath).toBe('snapshot');
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('graphdb backend negotiates ops-capable adapter path when operation mode is ops_preferred', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-graphdb-ops-capable-'));
+        const filePath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.v1.json');
+        let persisted = null;
+        let probeCount = 0;
+        let loadOpsCount = 0;
+        let saveOpsCount = 0;
+        const adapter = {
+            id: 'mock-graphdb-ops-capable',
+            getCapabilities() {
+                return {
+                    mode: 'ops_capable',
+                    supportedReadOperations: ['load_snapshot', 'load_snapshot_by_ops', 'probe_snapshot_metadata'],
+                    supportedWriteOperations: ['save_snapshot', 'save_snapshot_by_ops'],
+                };
+            },
+            async loadSnapshot() {
+                throw new Error('snapshot_path_should_not_be_used_when_ops_is_available');
+            },
+            async saveSnapshot() {
+                throw new Error('snapshot_path_should_not_be_used_when_ops_is_available');
+            },
+            async probeSnapshotMetadata() {
+                probeCount += 1;
+                if (!persisted) {
+                    return null;
+                }
+                return {
+                    schemaVersion: persisted.schemaVersion,
+                    savedAt: persisted.savedAt,
+                    atomCount: persisted.atoms.length,
+                    relationEdgeCount: persisted.relationEdges.length,
+                    temporalEdgeCount: persisted.temporalEdges.length,
+                    documentCount: persisted.documents.length,
+                };
+            },
+            async loadSnapshotByOps() {
+                loadOpsCount += 1;
+                return persisted;
+            },
+            async saveSnapshotByOps(snapshot) {
+                saveOpsCount += 1;
+                persisted = snapshot;
+            },
+            getDiagnostics() {
+                return {
+                    location: 'graphdb://mock-ops-capable',
+                    exists: persisted !== null,
+                    loaded: true,
+                    capabilityMode: 'ops_capable',
+                    supportedReadOperations: ['load_snapshot', 'load_snapshot_by_ops', 'probe_snapshot_metadata'],
+                    supportedWriteOperations: ['save_snapshot', 'save_snapshot_by_ops'],
+                    lastReadPath: 'ops',
+                    lastWritePath: 'ops',
+                };
+            },
+        };
+        try {
+            const store = (0, store_1.createKnowledgeGraphStore)({
+                backend: 'graphdb',
+                filePath,
+                graphdb: { adapter },
+                graphDbOperationMode: 'ops_preferred',
+            });
+            const snapshot = createSnapshot('graphdb_ops_capable_user');
+            await store.saveSnapshot(snapshot);
+            const restored = await store.loadSnapshot();
+            expect(restored).toEqual(snapshot);
+            expect(probeCount).toBeGreaterThanOrEqual(1);
+            expect(loadOpsCount).toBeGreaterThanOrEqual(1);
+            expect(saveOpsCount).toBeGreaterThanOrEqual(1);
+            const diagnostics = store.getDiagnostics();
+            expect(diagnostics.storeType).toBe('graphdb');
+            expect(diagnostics.graphDbOperationMode).toBe('ops_preferred');
+            expect(diagnostics.graphDbAdapterCapabilityMode).toBe('ops_capable');
+            expect(diagnostics.graphDbReadPath).toBe('ops');
+            expect(diagnostics.graphDbWritePath).toBe('ops');
+            expect(diagnostics.graphDbSupportedReadOperations).toEqual(expect.arrayContaining(['load_snapshot_by_ops', 'probe_snapshot_metadata']));
+            expect(diagnostics.graphDbSupportedWriteOperations).toEqual(expect.arrayContaining(['save_snapshot_by_ops']));
+            expect(diagnostics.graphDbLastSnapshotMetadata?.schemaVersion).toBe(1);
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('graphdb backend requires loadSnapshotByOps before classifying read path as ops', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-graphdb-probe-only-'));
+        const filePath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.v1.json');
+        let persisted = null;
+        let probeCount = 0;
+        let loadCount = 0;
+        let saveCount = 0;
+        const adapter = {
+            id: 'mock-graphdb-probe-only',
+            getCapabilities() {
+                return {
+                    mode: 'ops_capable',
+                    supportedReadOperations: ['load_snapshot', 'load_snapshot_by_ops', 'probe_snapshot_metadata'],
+                    supportedWriteOperations: ['save_snapshot', 'save_snapshot_by_ops'],
+                };
+            },
+            async loadSnapshot() {
+                loadCount += 1;
+                return persisted;
+            },
+            async saveSnapshot(snapshot) {
+                saveCount += 1;
+                persisted = snapshot;
+            },
+            async probeSnapshotMetadata() {
+                probeCount += 1;
+                return buildProbeMetadataFromSnapshot(persisted);
+            },
+        };
+        try {
+            const store = (0, store_1.createKnowledgeGraphStore)({
+                backend: 'graphdb',
+                filePath,
+                graphdb: { adapter },
+                graphDbFallbackEnabled: false,
+                graphDbOperationMode: 'ops_preferred',
+            });
+            const snapshot = createSnapshot('graphdb_probe_only_user');
+            await store.saveSnapshot(snapshot);
+            const restored = await store.loadSnapshot();
+            expect(restored).toEqual(snapshot);
+            expect(probeCount).toBeGreaterThanOrEqual(1);
+            expect(loadCount).toBeGreaterThanOrEqual(1);
+            expect(saveCount).toBeGreaterThanOrEqual(1);
+            const diagnostics = store.getDiagnostics();
+            expect(diagnostics.graphDbOperationMode).toBe('ops_preferred');
+            expect(diagnostics.graphDbAdapterCapabilityMode).toBe('ops_capable');
+            expect(diagnostics.graphDbReadPath).toBe('snapshot');
+            expect(diagnostics.graphDbWritePath).toBe('snapshot');
+            expect(diagnostics.usingFallback).toBe(false);
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('graphdb backend downgrades ops_preferred path to snapshot within adapter before fallback store', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-graphdb-ops-downgrade-'));
+        const filePath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.v1.json');
+        let persisted = null;
+        let loadOpsCount = 0;
+        let saveOpsCount = 0;
+        let loadSnapshotCount = 0;
+        let saveSnapshotCount = 0;
+        const adapter = {
+            id: 'mock-graphdb-ops-downgrade',
+            getCapabilities() {
+                return {
+                    mode: 'ops_capable',
+                    supportedReadOperations: ['load_snapshot', 'load_snapshot_by_ops'],
+                    supportedWriteOperations: ['save_snapshot', 'save_snapshot_by_ops'],
+                };
+            },
+            async loadSnapshotByOps() {
+                loadOpsCount += 1;
+                throw new Error('ops_read_path_unavailable');
+            },
+            async saveSnapshotByOps() {
+                saveOpsCount += 1;
+                throw new Error('ops_write_path_unavailable');
+            },
+            async loadSnapshot() {
+                loadSnapshotCount += 1;
+                return persisted;
+            },
+            async saveSnapshot(snapshot) {
+                saveSnapshotCount += 1;
+                persisted = snapshot;
+            },
+        };
+        try {
+            const store = (0, store_1.createKnowledgeGraphStore)({
+                backend: 'graphdb',
+                filePath,
+                graphdb: { adapter },
+                graphDbFallbackEnabled: false,
+                graphDbOperationMode: 'ops_preferred',
+            });
+            const snapshot = createSnapshot('graphdb_ops_downgrade_user');
+            await store.saveSnapshot(snapshot);
+            const restored = await store.loadSnapshot();
+            expect(restored).toEqual(snapshot);
+            expect(saveOpsCount).toBeGreaterThanOrEqual(1);
+            expect(loadOpsCount).toBeGreaterThanOrEqual(1);
+            expect(saveSnapshotCount).toBeGreaterThanOrEqual(1);
+            expect(loadSnapshotCount).toBeGreaterThanOrEqual(1);
+            const diagnostics = store.getDiagnostics();
+            expect(diagnostics.graphDbOperationMode).toBe('ops_preferred');
+            expect(diagnostics.graphDbAdapterCapabilityMode).toBe('ops_capable');
+            expect(diagnostics.graphDbReadPath).toBe('snapshot');
+            expect(diagnostics.graphDbWritePath).toBe('snapshot');
+            expect(diagnostics.usingFallback).toBe(false);
+            expect(diagnostics.lastError).toBeUndefined();
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('graphdb backend keeps snapshot path when adapter is snapshot-only even if operation mode requests ops', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-graphdb-ops-fallback-'));
+        const filePath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.v1.json');
+        let persisted = null;
+        let loadCount = 0;
+        let saveCount = 0;
+        const adapter = {
+            id: 'mock-graphdb-snapshot-only',
+            getCapabilities() {
+                return {
+                    mode: 'snapshot_only',
+                    supportedReadOperations: ['load_snapshot'],
+                    supportedWriteOperations: ['save_snapshot'],
+                };
+            },
+            async loadSnapshot() {
+                loadCount += 1;
+                return persisted;
+            },
+            async saveSnapshot(snapshot) {
+                saveCount += 1;
+                persisted = snapshot;
+            },
+            getDiagnostics() {
+                return {
+                    location: 'graphdb://mock-snapshot-only',
+                    exists: persisted !== null,
+                    loaded: true,
+                    capabilityMode: 'snapshot_only',
+                    supportedReadOperations: ['load_snapshot'],
+                    supportedWriteOperations: ['save_snapshot'],
+                    lastReadPath: 'snapshot',
+                    lastWritePath: 'snapshot',
+                };
+            },
+        };
+        try {
+            const store = (0, store_1.createKnowledgeGraphStore)({
+                backend: 'graphdb',
+                filePath,
+                graphdb: { adapter },
+                graphDbOperationMode: 'ops_preferred',
+            });
+            const snapshot = createSnapshot('graphdb_snapshot_only_user');
+            await store.saveSnapshot(snapshot);
+            const restored = await store.loadSnapshot();
+            expect(restored).toEqual(snapshot);
+            expect(loadCount).toBeGreaterThanOrEqual(1);
+            expect(saveCount).toBeGreaterThanOrEqual(1);
+            const diagnostics = store.getDiagnostics();
+            expect(diagnostics.graphDbOperationMode).toBe('ops_preferred');
+            expect(diagnostics.graphDbAdapterCapabilityMode).toBe('snapshot_only');
+            expect(diagnostics.graphDbReadPath).toBe('snapshot');
+            expect(diagnostics.graphDbWritePath).toBe('snapshot');
+            expect(diagnostics.graphDbSupportedReadOperations).toEqual(['load_snapshot']);
+            expect(diagnostics.graphDbSupportedWriteOperations).toEqual(['save_snapshot']);
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('graphdb backend fails closed when fallback is disabled and adapter is unavailable', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-graphdb-strict-no-adapter-'));
+        const filePath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.v1.json');
+        try {
+            const store = (0, store_1.createKnowledgeGraphStore)({
+                backend: 'graphdb',
+                filePath,
+                graphdb: { adapter: null },
+                graphDbFallbackEnabled: false,
+            });
+            const snapshot = createSnapshot('graphdb_strict_user');
+            await expect(store.saveSnapshot(snapshot)).rejects.toThrow('graphdb_adapter_unavailable_no_fallback');
+            await expect(store.loadSnapshot()).rejects.toThrow('graphdb_adapter_unavailable_no_fallback');
+            const diagnostics = store.getDiagnostics();
+            expect(diagnostics.storeType).toBe('graphdb');
+            expect(diagnostics.fallbackEnabled).toBe(false);
+            expect(diagnostics.usingFallback).toBe(false);
+            expect(diagnostics.graphDbOperationMode).toBe('snapshot_only');
+            expect(diagnostics.graphDbAdapterCapabilityMode).toBe('unknown');
+            expect(String(diagnostics.lastError || '')).toContain('graphdb_adapter_unavailable_no_fallback');
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('built-in file graphdb adapter persists snapshots to dedicated path', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-file-graphdb-'));
+        const graphDbPath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.graphdb.v1.json');
+        try {
+            const adapter = (0, store_1.createFileGraphDbSnapshotAdapter)({
+                provider: 'file',
+                filePath: graphDbPath,
+                id: 'file-graphdb-test',
+            });
+            expect(adapter).not.toBeNull();
+            const snapshot = createSnapshot('file_graphdb_user');
+            await adapter.saveSnapshot(snapshot);
+            const restored = await adapter.loadSnapshot();
+            expect(restored).toEqual(snapshot);
+            expect(fs.existsSync(graphDbPath)).toBe(true);
+            const diagnostics = adapter?.getDiagnostics ? adapter.getDiagnostics() : {};
+            expect(diagnostics.location).toContain('knowledge_graph_store.graphdb.v1.json');
+            expect(diagnostics.exists).toBe(true);
+            expect(diagnostics.capabilityMode).toBe('ops_capable');
+            expect(diagnostics.supportedReadOperations).toEqual(expect.arrayContaining(['load_snapshot', 'load_snapshot_by_ops', 'probe_snapshot_metadata']));
+            expect(diagnostics.supportedWriteOperations).toEqual(expect.arrayContaining(['save_snapshot', 'save_snapshot_by_ops']));
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('built-in http graphdb adapter persists snapshots through remote endpoint', async () => {
+        const mockServer = await startMockGraphDbSnapshotServer();
+        try {
+            const adapter = (0, store_1.createGraphDbSnapshotAdapter)({
+                provider: 'http',
+                filePath: '/tmp/unused.graphdb.v1.json',
+                adapterId: 'http-graphdb-test',
+                httpEndpoint: mockServer.endpoint,
+                httpTimeoutMs: 1200,
+                httpMaxRetries: 0,
+            });
+            expect(adapter).not.toBeNull();
+            expect(adapter?.id).toBe('http-graphdb-test');
+            const snapshot = createSnapshot('http_graphdb_user');
+            await adapter.saveSnapshot(snapshot);
+            const restored = await adapter.loadSnapshot();
+            expect(restored).toEqual(snapshot);
+            const diagnostics = adapter.getDiagnostics ? adapter.getDiagnostics() : {};
+            expect(String(diagnostics.location || '')).toContain('/graphdb/snapshot');
+            expect(diagnostics.exists).toBe(true);
+            expect(diagnostics.capabilityMode).toBe('ops_capable');
+            expect(diagnostics.supportedReadOperations).toEqual(expect.arrayContaining(['load_snapshot', 'get_node', 'query_nodes', 'query_edges', 'find_path']));
+            expect(diagnostics.supportedWriteOperations).toEqual(['save_snapshot']);
+            expect(diagnostics.requestedProvider).toBe('remote');
+            expect(diagnostics.resolvedProvider).toBe('remote');
+            expect(String(diagnostics.connector?.healthStatus || '')).toBe('ready');
+            expect(String(diagnostics.connector?.circuitState || '')).toBe('closed');
+            expect(Number(diagnostics.connector?.requestCount || 0)).toBeGreaterThanOrEqual(2);
+            expect(Number(diagnostics.connector?.successCount || 0)).toBeGreaterThanOrEqual(2);
+            expect(Number(diagnostics.connector?.failureCount || 0)).toBe(0);
+            expect(String(diagnostics.connector?.lastRequestId || '')).toContain('graphdb-mock-');
+            expect(mockServer.requests.some((item) => item.method === 'POST' && item.path === '/graphdb/snapshot')).toBe(true);
+            expect(mockServer.requests.some((item) => item.method === 'GET' && item.path === '/graphdb/snapshot')).toBe(true);
+        }
+        finally {
+            await mockServer.close();
+        }
+    });
+    test('reports a SQLite runtime fallback when a file adapter is supplied for a SQLite request', () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-provider-mismatch-'));
+        const filePath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.graphdb.v1.json');
+        try {
+            const adapter = (0, store_1.createFileGraphDbSnapshotAdapter)({ filePath, id: 'file-fallback-adapter' });
+            const store = (0, store_1.createKnowledgeGraphStore)({
+                backend: 'graphdb',
+                filePath,
+                graphdb: { adapter },
+                graphDbRequestedProvider: 'sqlite',
+                graphDbFallbackEnabled: true,
+            });
+            expect(store.getDiagnostics()).toEqual(expect.objectContaining({
+                requestedProvider: 'sqlite',
+                resolvedProvider: 'file',
+                fallbackReason: 'sqlite_runtime_unavailable',
+                storageEngine: 'file',
+            }));
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('returns an unavailable SQLite adapter instead of throwing when its parent path cannot be created', () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-sqlite-init-failure-'));
+        const parentFile = path.join(tempRoot, 'not-a-directory');
+        fs.writeFileSync(parentFile, 'occupied', 'utf8');
+        try {
+            const adapter = (0, store_1.createGraphDbSnapshotAdapter)({
+                provider: 'sqlite',
+                sqlitePath: path.join(parentFile, 'knowledge.sqlite'),
+            });
+            expect(adapter).toBeNull();
+            const fallbackPath = path.join(tempRoot, 'fallback', 'knowledge.json');
+            const store = (0, store_1.createKnowledgeGraphStore)({
+                backend: 'graphdb',
+                filePath: fallbackPath,
+                graphdb: { adapter: null },
+                graphDbRequestedProvider: 'sqlite',
+            });
+            expect(store.getDiagnostics()).toEqual(expect.objectContaining({
+                resolvedProvider: 'file',
+                fallbackReason: 'sqlite_runtime_unavailable',
+            }));
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('graphdb store proxies node/edge/path operations through http ops adapter when ops mode is preferred', async () => {
+        const mockServer = await startMockGraphDbSnapshotServer();
+        try {
+            const adapter = (0, store_1.createGraphDbSnapshotAdapter)({
+                provider: 'http',
+                filePath: '/tmp/unused.graphdb.v1.json',
+                adapterId: 'http-graphdb-ops-test',
+                httpEndpoint: mockServer.endpoint,
+                httpTimeoutMs: 1200,
+                httpMaxRetries: 0,
+            });
+            expect(adapter).not.toBeNull();
+            const store = (0, store_1.createKnowledgeGraphStore)({
+                backend: 'graphdb',
+                graphdb: { adapter },
+                graphDbFallbackEnabled: false,
+                graphDbOperationMode: 'ops_preferred',
+            });
+            const snapshot = createSnapshot('http_graphdb_ops_user');
+            snapshot.atoms = [
+                createAtom('atom_a', 'Alpha'),
+                createAtom('atom_b', 'Beta'),
+                createAtom('atom_c', 'Gamma'),
+            ];
+            snapshot.relationEdges = [
+                createRelation('edge_a_b', 'atom_a', 'atom_b'),
+                createRelation('edge_b_c', 'atom_b', 'atom_c'),
+            ];
+            await store.saveSnapshot(snapshot);
+            expect((0, store_1.isOpsAdapter)(store)).toBe(true);
+            if (!(0, store_1.isOpsAdapter)(store)) {
+                throw new Error('Expected ops adapter interface on graphdb store.');
+            }
+            const opsStore = store;
+            const node = await opsStore.getNode('atom_b');
+            expect(node?.id).toBe('atom_b');
+            const nodes = await opsStore.queryNodes({ nodeIds: ['atom_c', 'missing'] });
+            expect(nodes.map((item) => item.id)).toEqual(['atom_c']);
+            const edges = await opsStore.queryEdges({ fromNodeId: 'atom_a' });
+            expect(edges.map((item) => item.id)).toEqual(['edge_a_b']);
+            const pathResult = await opsStore.findPath('atom_a', 'atom_c', 4);
+            expect(pathResult.found).toBe(true);
+            expect(pathResult.path).toEqual(['atom_a', 'atom_b', 'atom_c']);
+            const diagnostics = store.getDiagnostics();
+            expect(diagnostics.graphDbQueryPath).toBe('ops');
+            expect(Number(diagnostics.graphDbQueryOpsReadCount || 0)).toBeGreaterThanOrEqual(4);
+            expect(String(diagnostics.graphDbAdapterCapabilityMode || '')).toBe('ops_capable');
+            expect(diagnostics.graphDbSupportedReadOperations).toEqual(expect.arrayContaining(['get_node', 'query_nodes', 'query_edges', 'find_path']));
+            expect(mockServer.requests.some((item) => item.path === '/graphdb/ops/node/atom_b')).toBe(true);
+            expect(mockServer.requests.some((item) => item.path === '/graphdb/ops/nodes')).toBe(true);
+            expect(mockServer.requests.some((item) => item.path === '/graphdb/ops/edges')).toBe(true);
+            expect(mockServer.requests.some((item) => item.path === '/graphdb/ops/path')).toBe(true);
+        }
+        finally {
+            await mockServer.close();
+        }
+    });
+    test('built-in sqlite graphdb adapter persists snapshots and serves ops locally', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-sqlite-graphdb-'));
+        const sqlitePath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.graphdb.v1.sqlite');
+        let adapter = null;
+        try {
+            adapter = (0, store_1.createGraphDbSnapshotAdapter)({
+                provider: 'sqlite',
+                sqlitePath,
+                adapterId: 'embedded-sqlite-graphdb-test',
+            });
+            expect(adapter).not.toBeNull();
+            const snapshot = createSnapshot('sqlite_graphdb_user');
+            snapshot.atoms = [
+                createAtom('atom_a', 'Alpha'),
+                createAtom('atom_b', 'Beta'),
+                createAtom('atom_c', 'Gamma'),
+            ];
+            snapshot.relationEdges = [
+                createRelation('edge_a_b', 'atom_a', 'atom_b'),
+                createRelation('edge_b_c', 'atom_b', 'atom_c'),
+            ];
+            await adapter.saveSnapshot(snapshot);
+            const restored = await adapter.loadSnapshot();
+            expect(restored).toEqual(snapshot);
+            const node = await adapter.getNodeByOps?.('atom_b');
+            expect(node?.id).toBe('atom_b');
+            const nodes = await adapter.queryNodesByOps?.({ nodeIds: ['atom_c', 'missing'] });
+            expect(nodes?.map((item) => item.id)).toEqual(['atom_c']);
+            const edges = await adapter.queryEdgesByOps?.({ fromNodeId: 'atom_a' });
+            expect(edges?.map((item) => item.id)).toEqual(['edge_a_b']);
+            const pathResult = await adapter.findPathByOps?.('atom_a', 'atom_c', 4);
+            expect(pathResult?.found).toBe(true);
+            expect(pathResult?.path).toEqual(['atom_a', 'atom_b', 'atom_c']);
+            const diagnostics = adapter.getDiagnostics ? adapter.getDiagnostics() : {};
+            expect(String(diagnostics.location || '')).toContain('knowledge_graph_store.graphdb.v1.sqlite');
+            expect(diagnostics.storeType).toBe('graphdb');
+            expect(String(diagnostics.storageEngine || '')).toBe('sqlite');
+            expect(diagnostics.requestedProvider).toBe('sqlite');
+            expect(diagnostics.resolvedProvider).toBe('sqlite');
+            expect(diagnostics.fallbackReason).toBeUndefined();
+            expect(diagnostics.capabilityMode).toBe('ops_capable');
+            expect(diagnostics.supportedReadOperations).toEqual(expect.arrayContaining(['load_snapshot', 'get_node', 'query_nodes', 'query_edges', 'find_path']));
+            expect(diagnostics.supportedWriteOperations).toEqual(['save_snapshot']);
+        }
+        finally {
+            try {
+                adapter?.close?.();
+            }
+            catch {
+            }
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('graphdb sqlite store diagnostics refresh snapshot metadata after snapshot writes', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-sqlite-store-diag-'));
+        const sqlitePath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.graphdb.v1.sqlite');
+        const fallbackPath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.v1.json');
+        let adapter = null;
+        try {
+            adapter = (0, store_1.createGraphDbSnapshotAdapter)({
+                provider: 'sqlite',
+                sqlitePath,
+                adapterId: 'embedded-sqlite-graphdb-diagnostics-test',
+            });
+            expect(adapter).not.toBeNull();
+            const store = (0, store_1.createKnowledgeGraphStore)({
+                backend: 'graphdb',
+                filePath: fallbackPath,
+                graphdb: {
+                    adapter,
+                },
+                graphDbFallbackEnabled: false,
+                graphDbOperationMode: 'ops_preferred',
+            });
+            const snapshot = createSnapshot('sqlite_store_diag_user');
+            snapshot.atoms = [
+                createAtom('atom_diag_a', 'Diag Alpha'),
+                createAtom('atom_diag_b', 'Diag Beta'),
+            ];
+            snapshot.relationEdges = [
+                createRelation('edge_diag_a_b', 'atom_diag_a', 'atom_diag_b'),
+            ];
+            snapshot.documents = [
+                {
+                    documentId: 'doc_diag',
+                    sourcePath: '/diag/doc.md',
+                    sourceHash: 'doc_diag_hash',
+                    version: 1,
+                    updatedAt: new Date('2026-01-01T00:00:00.000Z').toISOString(),
+                    atomStableKeyToId: [
+                        ['atom_diag_a_stable', 'atom_diag_a'],
+                        ['atom_diag_b_stable', 'atom_diag_b'],
+                    ],
+                    atomIds: ['atom_diag_a', 'atom_diag_b'],
+                    evidenceSpanIds: [],
+                    relationEdgeIds: ['edge_diag_a_b'],
+                    temporalEdgeIds: [],
+                },
+            ];
+            await store.saveSnapshot(snapshot);
+            const diagnostics = store.getDiagnostics();
+            expect(diagnostics.storeType).toBe('graphdb');
+            expect(diagnostics.storageEngine).toBe('sqlite');
+            expect(diagnostics.graphDbLastSnapshotMetadata).toEqual(expect.objectContaining({
+                schemaVersion: 1,
+                atomCount: 2,
+                relationEdgeCount: 1,
+                documentCount: 1,
+            }));
+        }
+        finally {
+            try {
+                adapter?.close?.();
+            }
+            catch {
+            }
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('sqlite graphdb adapter reopens after close and replays the last committed snapshot', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-sqlite-replay-'));
+        const sqlitePath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.graphdb.v1.sqlite');
+        let firstAdapter = null;
+        let secondAdapter = null;
+        try {
+            firstAdapter = (0, store_1.createGraphDbSnapshotAdapter)({
+                provider: 'sqlite',
+                sqlitePath,
+                adapterId: 'embedded-sqlite-replay-before-close',
+            });
+            expect(firstAdapter).not.toBeNull();
+            const snapshot = createSnapshot('sqlite_restart_user');
+            snapshot.atoms = [createAtom('restart_atom', 'Restart Alpha')];
+            snapshot.documents = [{
+                    documentId: 'restart_doc',
+                    sourcePath: 'restart.md',
+                    sourceHash: 'restart_hash',
+                    version: 1,
+                    updatedAt: '2026-01-01T00:00:00.000Z',
+                    atomStableKeyToId: [['restart_stable', 'restart_atom']],
+                    atomIds: ['restart_atom'],
+                    evidenceSpanIds: [],
+                    relationEdgeIds: [],
+                    temporalEdgeIds: [],
+                }];
+            await firstAdapter.saveSnapshot(snapshot);
+            firstAdapter.close?.();
+            secondAdapter = (0, store_1.createGraphDbSnapshotAdapter)({
+                provider: 'sqlite',
+                sqlitePath,
+                adapterId: 'embedded-sqlite-replay-after-close',
+            });
+            expect(secondAdapter).not.toBeNull();
+            await expect(secondAdapter.loadSnapshot()).resolves.toEqual(snapshot);
+            await expect(secondAdapter.getNodeByOps?.('restart_atom')).resolves.toEqual(snapshot.atoms[0]);
+            await expect(secondAdapter.probeSnapshotMetadata?.()).resolves.toEqual(expect.objectContaining({
+                atomCount: 1,
+                documentCount: 1,
+            }));
+        }
+        finally {
+            try {
+                firstAdapter?.close?.();
+                secondAdapter?.close?.();
+            }
+            catch {
+            }
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('graphdb store diagnostics restores snapshot metadata after reopening the sqlite adapter', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-store-sqlite-diagnostics-reopen-'));
+        const sqlitePath = path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.graphdb.v1.sqlite');
+        let firstAdapter = null;
+        let secondAdapter = null;
+        let firstStore = null;
+        let secondStore = null;
+        try {
+            const snapshot = createSnapshot('sqlite_store_diagnostics_reopen_user');
+            snapshot.atoms = [createAtom('reopen_atom', 'Reopen Alpha')];
+            snapshot.documents = [{
+                    documentId: 'reopen_doc',
+                    sourcePath: '/reopen/doc.md',
+                    sourceHash: 'reopen_hash',
+                    version: 1,
+                    updatedAt: '2026-01-01T00:00:00.000Z',
+                    atomStableKeyToId: [['reopen_atom_stable', 'reopen_atom']],
+                    atomIds: ['reopen_atom'],
+                    evidenceSpanIds: [],
+                    relationEdgeIds: [],
+                    temporalEdgeIds: [],
+                }];
+            firstAdapter = (0, store_1.createGraphDbSnapshotAdapter)({ provider: 'sqlite', sqlitePath, adapterId: 'sqlite-diagnostics-reopen-first' });
+            expect(firstAdapter).not.toBeNull();
+            firstStore = (0, store_1.createKnowledgeGraphStore)({
+                backend: 'graphdb',
+                graphdb: { adapter: firstAdapter },
+                graphDbFallbackEnabled: false,
+                graphDbOperationMode: 'ops_preferred',
+            });
+            await firstStore.saveSnapshot(snapshot);
+            firstStore.close?.();
+            firstStore = null;
+            firstAdapter = null;
+            secondAdapter = (0, store_1.createGraphDbSnapshotAdapter)({ provider: 'sqlite', sqlitePath, adapterId: 'sqlite-diagnostics-reopen-second' });
+            expect(secondAdapter).not.toBeNull();
+            secondStore = (0, store_1.createKnowledgeGraphStore)({
+                backend: 'graphdb',
+                graphdb: { adapter: secondAdapter },
+                graphDbFallbackEnabled: false,
+                graphDbOperationMode: 'ops_preferred',
+            });
+            await expect(secondStore.loadSnapshot()).resolves.toEqual(snapshot);
+            expect(secondStore.getDiagnostics().graphDbLastSnapshotMetadata).toEqual(expect.objectContaining({
+                atomCount: 1,
+                documentCount: 1,
+            }));
+        }
+        finally {
+            try {
+                firstStore?.close?.();
+            }
+            catch { }
+            try {
+                secondStore?.close?.();
+            }
+            catch { }
+            try {
+                firstAdapter?.close?.();
+            }
+            catch { }
+            try {
+                secondAdapter?.close?.();
+            }
+            catch { }
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('graphdb store diagnostics derives metadata from ops reads when the adapter has no probe method', async () => {
+        const snapshot = createSnapshot('ops_read_metadata_user');
+        snapshot.atoms = [createAtom('ops_read_atom', 'Ops Read Alpha')];
+        snapshot.documents = [{
+                documentId: 'ops_read_doc',
+                sourcePath: '/ops-read/doc.md',
+                sourceHash: 'ops_read_hash',
+                version: 1,
+                updatedAt: '2026-01-01T00:00:00.000Z',
+                atomStableKeyToId: [['ops_read_atom_stable', 'ops_read_atom']],
+                atomIds: ['ops_read_atom'],
+                evidenceSpanIds: [],
+                relationEdgeIds: [],
+                temporalEdgeIds: [],
+            }];
+        const adapter = {
+            id: 'ops-only-without-probe',
+            opsCapable: true,
+            loadSnapshot: async () => snapshot,
+            saveSnapshot: async () => undefined,
+            loadSnapshotByOps: async () => snapshot,
+            saveSnapshotByOps: async () => undefined,
+            getCapabilities: () => ({ mode: 'ops_capable', snapshotSupported: true, writeSupported: true }),
+        };
+        const store = (0, store_1.createKnowledgeGraphStore)({
+            backend: 'graphdb',
+            graphdb: { adapter },
+            graphDbFallbackEnabled: false,
+            graphDbOperationMode: 'ops_preferred',
+        });
+        await expect(store.loadSnapshot()).resolves.toEqual(snapshot);
+        expect(store.getDiagnostics().graphDbLastSnapshotMetadata).toEqual(expect.objectContaining({
+            atomCount: 1,
+            documentCount: 1,
+        }));
+    });
+    test('built-in http graphdb adapter surfaces circuit-open telemetry after repeated transient failures', async () => {
+        const server = http.createServer((req, res) => {
+            const method = String(req.method || 'GET').toUpperCase();
+            const requestPath = String(req.url || '');
+            if (requestPath !== '/graphdb/snapshot' || method !== 'GET') {
+                res.statusCode = 404;
+                res.setHeader('Content-Type', 'application/json');
+                res.setHeader('X-Request-Id', 'graphdb-flaky-nf');
+                res.setHeader('X-Error-Code', 'not_found');
+                res.end(JSON.stringify({ error: 'not_found' }));
+                return;
+            }
+            res.statusCode = 503;
+            res.setHeader('Content-Type', 'application/json');
+            res.setHeader('X-Request-Id', 'graphdb-flaky-503');
+            res.setHeader('X-Error-Code', 'overloaded');
+            res.end(JSON.stringify({ error: 'overloaded' }));
+        });
+        const port = await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(0, '127.0.0.1', () => {
+                const address = server.address();
+                if (!address || typeof address !== 'object') {
+                    reject(new Error('Failed to allocate graphdb flaky mock port.'));
+                    return;
+                }
+                resolve(address.port);
+            });
+        });
+        try {
+            const adapter = (0, store_1.createGraphDbSnapshotAdapter)({
+                provider: 'http',
+                filePath: '/tmp/unused.graphdb.v1.json',
+                adapterId: 'http-graphdb-circuit',
+                httpEndpoint: `http://127.0.0.1:${port}/graphdb`,
+                httpTimeoutMs: 1200,
+                httpMaxRetries: 0,
+                httpRetryDelayMs: 0,
+                httpCircuitFailureThreshold: 2,
+                httpCircuitCooldownMs: 60000,
+            });
+            expect(adapter).not.toBeNull();
+            await expect(adapter.loadSnapshot()).rejects.toThrow('graphdb_http_request_failed:503');
+            await expect(adapter.loadSnapshot()).rejects.toThrow('graphdb_http_request_failed:503');
+            await expect(adapter.loadSnapshot()).rejects.toThrow('graphdb_http_circuit_open');
+            const diagnostics = adapter.getDiagnostics ? adapter.getDiagnostics() : {};
+            expect(String(diagnostics.connector?.healthStatus || '')).toBe('unavailable');
+            expect(String(diagnostics.connector?.circuitState || '')).toBe('open');
+            expect(Number(diagnostics.connector?.shortCircuitCount || 0)).toBeGreaterThanOrEqual(1);
+            expect(Number(diagnostics.connector?.failureCount || 0)).toBeGreaterThanOrEqual(2);
+            expect(String(diagnostics.connector?.lastErrorCode || '')).toBe('circuit_open');
+        }
+        finally {
+            await new Promise((resolve, reject) => {
+                server.close((error) => {
+                    if (error) {
+                        reject(error);
+                        return;
+                    }
+                    resolve();
+                });
+            });
+        }
+    });
+});