@sigloch/graph-api-core 0.4.0

package/dist/graph-service.js

@@ -0,0 +1,597 @@
+/**
+ * GraphService — central facade for all graph operations.
+ * Framework-agnostic, ontology-agnostic.
+ *
+ * CR-195d: Enhanced mutate with hoisting, meta-model validation, audit traces.
+ */
+import { isValidTrace, tracePatternsOf } from './types.js';
+import { FormatECodec } from './format-e-codec.js';
+import { DefaultRuleEngine } from './rule-engine.js';
+import { InMemoryAuditLog } from './audit.js';
+import { extractFromSemanticId } from '@sigloch/contracts/se';
+import { updateEdge, mergeNodes } from './edge-ops.js';
+export class GraphService {
+    ontology;
+    codec;
+    storage;
+    rules;
+    audit;
+    scope;
+    /** Trace-legality patterns (CR-GC-247) — the SSOT every edge validates against. */
+    patterns;
+    version = 0;
+    constructor(config) {
+        this.ontology = config.ontology;
+        this.patterns = tracePatternsOf(config.ontology);
+        this.storage = config.storage;
+        this.rules = config.ruleEngine ?? new DefaultRuleEngine(config.ontology.version);
+        this.audit = config.auditLog ?? new InMemoryAuditLog();
+        this.scope = config.scope ?? { workspaceId: 'default', systemId: 'default' };
+        this.codec = new FormatECodec(config.ontology);
+        // Register domain rules
+        if (config.ontology.rules) {
+            this.rules.register(config.ontology.rules);
+        }
+    }
+    async initialize() {
+        await this.storage.initialize();
+    }
+    async shutdown() {
+        await this.storage.shutdown();
+    }
+    // ---------------------------------------------------------------------------
+    // Queries
+    // ---------------------------------------------------------------------------
+    async query(q) {
+        if (q.type === 'subgraph' && q.root) {
+            return this.storage.getSubgraph(q.root, q.depth ?? 3);
+        }
+        return this.storage.loadGraph(this.scope);
+    }
+    async getElement(uid) {
+        return this.storage.getNode(uid);
+    }
+    async getSubgraph(root, depth = 3) {
+        return this.storage.getSubgraph(root, depth);
+    }
+    // ---------------------------------------------------------------------------
+    // Mutations
+    // ---------------------------------------------------------------------------
+    async mutate(diff, consumerId = 'system') {
+        let applied = 0;
+        let rejected = 0;
+        const violations = [];
+        const nodesToCreate = [];
+        const edgesToCreate = [];
+        // CR-195d: Hoist kinds/asil/method from attributes to top-level for SE schema
+        const isSESchema = this.ontology.name === 'SE';
+        for (const op of diff.operations) {
+            switch (op.type) {
+                case 'add_node': {
+                    const existing = await this.storage.getNode(op.semanticId);
+                    if (existing) {
+                        // CR-169: Upsert — update existing
+                        try {
+                            const updated = await this.applyNodeUpdate(existing, op, isSESchema);
+                            await this.storage.saveNodes([updated]);
+                            applied++;
+                        }
+                        catch (e) {
+                            violations.push({
+                                ruleId: 'UPDATE_FAILED',
+                                ruleName: 'update-failed',
+                                severity: 'error',
+                                message: e.message,
+                                elementId: op.semanticId,
+                            });
+                            rejected++;
+                        }
+                    }
+                    else {
+                        // New node
+                        try {
+                            const node = await this.applyNodeCreate(op, isSESchema);
+                            await this.storage.saveNodes([node]);
+                            nodesToCreate.push(op.semanticId);
+                            if (consumerId !== 'system') {
+                                edgesToCreate.push({
+                                    sourceId: consumerId,
+                                    targetId: op.semanticId,
+                                    edgeType: 'produces',
+                                });
+                            }
+                            applied++;
+                        }
+                        catch (e) {
+                            violations.push({
+                                ruleId: 'CREATE_FAILED',
+                                ruleName: 'create-failed',
+                                severity: 'error',
+                                message: e.message,
+                                elementId: op.semanticId,
+                            });
+                            rejected++;
+                        }
+                    }
+                    break;
+                }
+                case 'strict_add_node': {
+                    const existing = await this.storage.getNode(op.semanticId);
+                    if (existing) {
+                        violations.push({
+                            ruleId: 'STRICT_ADD',
+                            ruleName: 'strict-add',
+                            severity: 'error',
+                            message: `Node already exists: ${op.semanticId}`,
+                            elementId: op.semanticId,
+                        });
+                        rejected++;
+                        continue;
+                    }
+                    try {
+                        const node = await this.applyNodeCreate(op, isSESchema);
+                        await this.storage.saveNodes([node]);
+                        nodesToCreate.push(op.semanticId);
+                        if (consumerId !== 'system') {
+                            edgesToCreate.push({
+                                sourceId: consumerId,
+                                targetId: op.semanticId,
+                                edgeType: 'produces',
+                            });
+                        }
+                        applied++;
+                    }
+                    catch (e) {
+                        violations.push({
+                            ruleId: 'CREATE_FAILED',
+                            ruleName: 'create-failed',
+                            severity: 'error',
+                            message: e.message,
+                            elementId: op.semanticId,
+                        });
+                        rejected++;
+                    }
+                    break;
+                }
+                case 'update_node': {
+                    const existing = await this.storage.getNode(op.semanticId);
+                    if (!existing) {
+                        violations.push({
+                            ruleId: 'UPDATE_MISSING',
+                            ruleName: 'update-missing',
+                            severity: 'warning',
+                            message: `Node not found for update: ${op.semanticId}`,
+                            elementId: op.semanticId,
+                        });
+                        rejected++;
+                        continue;
+                    }
+                    try {
+                        const updated = await this.applyNodeUpdate(existing, op, isSESchema);
+                        await this.storage.saveNodes([updated]);
+                        applied++;
+                    }
+                    catch (e) {
+                        violations.push({
+                            ruleId: 'UPDATE_FAILED',
+                            ruleName: 'update-failed',
+                            severity: 'error',
+                            message: e.message,
+                            elementId: op.semanticId,
+                        });
+                        rejected++;
+                    }
+                    break;
+                }
+                case 'remove_node': {
+                    await this.storage.deleteNodes([op.semanticId]);
+                    applied++;
+                    break;
+                }
+                case 'add_edge': {
+                    if (!op.sourceId || !op.targetId || !op.edgeType) {
+                        violations.push({
+                            ruleId: 'EDGE_INVALID',
+                            ruleName: 'edge-invalid',
+                            severity: 'error',
+                            message: 'Edge missing source/target/type',
+                        });
+                        rejected++;
+                        continue;
+                    }
+                    try {
+                        await this.validateAndApplyEdge({
+                            sourceId: op.sourceId,
+                            targetId: op.targetId,
+                            edgeType: op.edgeType,
+                        });
+                        const edge = {
+                            sourceId: op.sourceId,
+                            targetId: op.targetId,
+                            edgeType: op.edgeType,
+                            attributes: op.attributes ? { ...op.attributes } : {},
+                        };
+                        await this.storage.saveEdges([edge]);
+                        applied++;
+                    }
+                    catch (e) {
+                        violations.push({
+                            ruleId: 'EDGE_INVALID',
+                            ruleName: 'edge-invalid',
+                            severity: 'error',
+                            message: e.message,
+                        });
+                        rejected++;
+                    }
+                    break;
+                }
+                case 'strict_add_edge': {
+                    if (!op.sourceId || !op.targetId || !op.edgeType) {
+                        violations.push({
+                            ruleId: 'EDGE_INVALID',
+                            ruleName: 'edge-invalid',
+                            severity: 'error',
+                            message: 'Edge missing source/target/type',
+                        });
+                        rejected++;
+                        continue;
+                    }
+                    try {
+                        // Check if edge already exists
+                        const existing = await this.storage.loadGraph(this.scope);
+                        const edgeExists = existing.edges.some(e => e.sourceId === op.sourceId && e.targetId === op.targetId && e.edgeType === op.edgeType);
+                        if (edgeExists) {
+                            violations.push({
+                                ruleId: 'STRICT_EDGE_EXISTS',
+                                ruleName: 'strict-edge-exists',
+                                severity: 'error',
+                                message: `Edge already exists: ${op.sourceId} -${op.edgeType}-> ${op.targetId}`,
+                            });
+                            rejected++;
+                            continue;
+                        }
+                        await this.validateAndApplyEdge({
+                            sourceId: op.sourceId,
+                            targetId: op.targetId,
+                            edgeType: op.edgeType,
+                        });
+                        const edge = {
+                            sourceId: op.sourceId,
+                            targetId: op.targetId,
+                            edgeType: op.edgeType,
+                            attributes: op.attributes ? { ...op.attributes } : {},
+                        };
+                        await this.storage.saveEdges([edge]);
+                        applied++;
+                    }
+                    catch (e) {
+                        violations.push({
+                            ruleId: 'EDGE_INVALID',
+                            ruleName: 'edge-invalid',
+                            severity: 'error',
+                            message: e.message,
+                        });
+                        rejected++;
+                    }
+                    break;
+                }
+                case 'remove_edge': {
+                    if (!op.sourceId || !op.targetId || !op.edgeType) {
+                        rejected++;
+                        continue;
+                    }
+                    await this.storage.deleteEdges([{
+                            sourceId: op.sourceId,
+                            targetId: op.targetId,
+                            edgeType: op.edgeType,
+                        }]);
+                    applied++;
+                    break;
+                }
+                case 'update_edge': {
+                    if (!op.sourceId || !op.targetId || !op.edgeType || !op.set) {
+                        violations.push({
+                            ruleId: 'EDGE_INVALID',
+                            ruleName: 'edge-invalid',
+                            severity: 'error',
+                            message: 'update_edge requires sourceId/targetId/edgeType identity and a set{} patch',
+                        });
+                        rejected++;
+                        continue;
+                    }
+                    try {
+                        const graph = await this.storage.loadGraph(this.scope);
+                        const { removed, added } = updateEdge(graph, { sourceId: op.sourceId, targetId: op.targetId, edgeType: op.edgeType }, op.set);
+                        await this.validateAndApplyEdge({
+                            sourceId: added.sourceId, targetId: added.targetId, edgeType: added.edgeType,
+                        });
+                        await this.storage.deleteEdges([{
+                                sourceId: removed.sourceId, targetId: removed.targetId, edgeType: removed.edgeType,
+                            }]);
+                        await this.storage.saveEdges([added]);
+                        applied++;
+                    }
+                    catch (e) {
+                        violations.push({
+                            ruleId: 'EDGE_INVALID',
+                            ruleName: 'edge-invalid',
+                            severity: 'error',
+                            message: e.message,
+                            elementId: op.semanticId,
+                        });
+                        rejected++;
+                    }
+                    break;
+                }
+                case 'merge_nodes': {
+                    if (!op.sourceIds || op.sourceIds.length !== 2) {
+                        violations.push({
+                            ruleId: 'MERGE_UNSUPPORTED',
+                            ruleName: 'merge-unsupported',
+                            severity: 'error',
+                            message: `merge_nodes requires exactly 2 sourceIds (source absorbed into target); got ${op.sourceIds?.length ?? 0}`,
+                            elementId: op.semanticId,
+                        });
+                        rejected++;
+                        continue;
+                    }
+                    const [sourceUid, targetUid] = op.sourceIds;
+                    try {
+                        const graph = await this.storage.loadGraph(this.scope);
+                        const { removedNode, removedEdges, addedEdges } = mergeNodes(graph, sourceUid, targetUid);
+                        for (const edge of addedEdges) {
+                            await this.validateAndApplyEdge({
+                                sourceId: edge.sourceId, targetId: edge.targetId, edgeType: edge.edgeType,
+                            });
+                        }
+                        if (removedEdges.length > 0) {
+                            await this.storage.deleteEdges(removedEdges.map(e => ({
+                                sourceId: e.sourceId, targetId: e.targetId, edgeType: e.edgeType,
+                            })));
+                        }
+                        if (addedEdges.length > 0) {
+                            await this.storage.saveEdges(addedEdges);
+                        }
+                        await this.storage.deleteNodes([removedNode]);
+                        applied++;
+                    }
+                    catch (e) {
+                        violations.push({
+                            ruleId: 'MERGE_INVALID',
+                            ruleName: 'merge-invalid',
+                            severity: 'error',
+                            message: e.message,
+                            elementId: op.semanticId,
+                        });
+                        rejected++;
+                    }
+                    break;
+                }
+                default:
+                    rejected++;
+            }
+        }
+        // CR-195d: Create produces edges for newly created nodes (audit trail)
+        if (edgesToCreate.length > 0) {
+            try {
+                await this.storage.saveEdges(edgesToCreate.map(e => ({
+                    ...e,
+                    attributes: {},
+                })));
+            }
+            catch (e) {
+                console.warn('[GraphService] Failed to create audit produces edges:', e);
+            }
+        }
+        // Add parse errors as violations
+        for (const err of diff.errors) {
+            violations.push({
+                ruleId: 'PARSE_ERROR',
+                ruleName: 'parse-error',
+                severity: 'error',
+                message: err,
+            });
+            rejected++;
+        }
+        this.version++;
+        const auditId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const result = rejected === 0 ? 'applied' : applied === 0 ? 'rejected' : 'partial';
+        await this.audit.record({
+            id: auditId,
+            timestamp: new Date().toISOString(),
+            consumerId,
+            consumerType: 'automation',
+            operation: 'mutate',
+            diff,
+            result,
+            violations: violations.length > 0 ? violations : undefined,
+            graphVersion: this.version,
+        });
+        return { applied, rejected, violations, version: this.version, auditId };
+    }
+    async applyBatch(diffs, consumerId = 'system') {
+        const results = [];
+        let totalApplied = 0;
+        let totalRejected = 0;
+        for (const diff of diffs) {
+            const result = await this.mutate(diff, consumerId);
+            results.push(result);
+            totalApplied += result.applied;
+            totalRejected += result.rejected;
+        }
+        return { results, totalApplied, totalRejected };
+    }
+    // ---------------------------------------------------------------------------
+    // Validation
+    // ---------------------------------------------------------------------------
+    async validate() {
+        const graph = await this.storage.loadGraph(this.scope);
+        return this.rules.evaluate(graph);
+    }
+    // ---------------------------------------------------------------------------
+    // Export
+    // ---------------------------------------------------------------------------
+    async export(format = 'json') {
+        const graph = await this.storage.loadGraph(this.scope);
+        if (format === 'format-e') {
+            return this.codec.serialize(graph);
+        }
+        return JSON.stringify(graph, null, 2);
+    }
+    // ---------------------------------------------------------------------------
+    // Health
+    // ---------------------------------------------------------------------------
+    async health() {
+        const healthy = await this.storage.isHealthy();
+        const stats = await this.storage.stats();
+        const violations = await this.validate();
+        return {
+            status: healthy ? 'ok' : 'down',
+            storage: this.storage.name,
+            ontologyName: this.ontology.name,
+            ontologyVersion: this.ontology.version,
+            elementCount: stats.nodeCount,
+            edgeCount: stats.edgeCount,
+            violationCount: violations.filter(v => v.severity === 'error').length,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Helpers
+    // ---------------------------------------------------------------------------
+    async applyNodeCreate(op, isSESchema) {
+        let type;
+        let name;
+        if (isSESchema) {
+            try {
+                const { type: extractedType, name: extractedName } = extractFromSemanticId(op.semanticId);
+                type = extractedType;
+                name = extractedName;
+            }
+            catch {
+                throw new Error(`Invalid semantic ID: ${op.semanticId}`);
+            }
+        }
+        else {
+            const parts = op.semanticId.split('.');
+            if (parts.length >= 3)
+                type = parts[parts.length - 2];
+            else if (parts.length === 2)
+                type = parts[1];
+            else
+                type = 'UNKNOWN';
+            name = parts[0];
+        }
+        const attributes = op.attributes ? { ...op.attributes } : {};
+        // CR-195d: Hoist kinds/asil/method from attributes to OntologyElement (via se_blob)
+        if (isSESchema) {
+            const element = {
+                id: op.semanticId,
+                type: type,
+                name,
+                description: op.description ?? name,
+                status: 'draft',
+                created_at: new Date().toISOString(),
+                attributes: { ...attributes },
+            };
+            // Hoist top-level fields
+            if (element.attributes) {
+                if (element.attributes.kinds != null) {
+                    const raw = String(element.attributes.kinds);
+                    element.kinds = raw.includes(',')
+                        ? raw.split(',').map((s) => s.trim())
+                        : [raw.trim()];
+                    delete element.attributes.kinds;
+                }
+                if (element.attributes.asil != null) {
+                    element.asil = String(element.attributes.asil);
+                    delete element.attributes.asil;
+                }
+                if (element.attributes.method != null) {
+                    element.method = String(element.attributes.method);
+                    delete element.attributes.method;
+                }
+            }
+            return {
+                uid: op.semanticId,
+                type,
+                name,
+                description: op.description ?? name,
+                attributes: { se_blob: JSON.stringify(element) },
+                createdAt: new Date().toISOString(),
+            };
+        }
+        return {
+            uid: op.semanticId,
+            type,
+            name,
+            description: op.description,
+            attributes,
+            createdAt: new Date().toISOString(),
+        };
+    }
+    async applyNodeUpdate(existing, op, isSESchema) {
+        if (isSESchema && existing.attributes.se_blob) {
+            try {
+                const element = JSON.parse(String(existing.attributes.se_blob));
+                if (op.description)
+                    element.description = op.description;
+                if (op.attributes && Object.keys(op.attributes).length > 0) {
+                    element.attributes = { ...element.attributes, ...op.attributes };
+                }
+                // Hoist top-level fields
+                if (element.attributes) {
+                    if (element.attributes.kinds != null) {
+                        const raw = String(element.attributes.kinds);
+                        element.kinds = raw.includes(',')
+                            ? raw.split(',').map((s) => s.trim())
+                            : [raw.trim()];
+                        delete element.attributes.kinds;
+                    }
+                    if (element.attributes.asil != null) {
+                        element.asil = String(element.attributes.asil);
+                        delete element.attributes.asil;
+                    }
+                    if (element.attributes.method != null) {
+                        element.method = String(element.attributes.method);
+                        delete element.attributes.method;
+                    }
+                }
+                element.updated_at = new Date().toISOString();
+                return {
+                    ...existing,
+                    description: op.description ?? existing.description,
+                    attributes: { se_blob: JSON.stringify(element) },
+                    updatedAt: new Date().toISOString(),
+                };
+            }
+            catch (e) {
+                throw new Error(`Failed to parse se_blob: ${e.message}`);
+            }
+        }
+        return {
+            ...existing,
+            description: op.description ?? existing.description,
+            attributes: { ...existing.attributes, ...op.attributes },
+            updatedAt: new Date().toISOString(),
+        };
+    }
+    // CR-GC-247: one legality path for every ontology (SE + foreign). The edge type
+    // must be declared (menu enumeration via edgeTypes), then the (source,target,type)
+    // trace is checked against descriptor.patterns via the single isValidTrace —
+    // no SE/foreign fork, no validPairs re-implementation.
+    async validateAndApplyEdge(op) {
+        if (!this.ontology.edgeTypes[op.edgeType]) {
+            const known = Object.keys(this.ontology.edgeTypes).join(', ');
+            throw new Error(`Unknown edge type '${op.edgeType}' in ontology '${this.ontology.name}' (known: ${known || 'none'})`);
+        }
+        const src = await this.storage.getNode(op.sourceId);
+        const tgt = await this.storage.getNode(op.targetId);
+        if (src && tgt && !isValidTrace({ source: src.type, target: tgt.type, type: op.edgeType }, this.patterns)) {
+            const allowed = this.patterns
+                .filter(p => p.type === op.edgeType)
+                .map(p => `${p.source}->${p.target}`)
+                .join(', ');
+            throw new Error(`Invalid ontology trace: ${src.type} -${op.edgeType}-> ${tgt.type} (allowed: ${allowed || 'none'})`);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @sigloch/graph-api-core
+ * Framework-agnostic graph operations library with pluggable adapters.
+ * One contract (Zod), one operations layer (GraphService), N adapters.
+ *
+ * @author andreas@siglochconsulting
+ */
+export type { GraphNode, GraphEdge, Graph } from './types.js';
+export type { OntologyDescriptor, NodeTypeDescriptor, EdgeTypeDescriptor, TracePattern } from './types.js';
+export { isValidTrace, tracePatternsOf } from './types.js';
+export type { GraphScope, GraphQuery, MutationResult, BatchResult, HealthStatus } from './types.js';
+export type { FormatEOperation, FormatEDiff } from './types.js';
+export { GraphNodeSchema, GraphEdgeSchema, GraphSchema, GraphScopeSchema, GraphQuerySchema, MutationResultSchema, HealthStatusSchema, } from './schemas.js';
+export { GraphService } from './graph-service.js';
+export { FormatECodec } from './format-e-codec.js';
+export type { Rule, RuleViolation, RuleEngine } from './rule-engine.js';
+export { DefaultRuleEngine } from './rule-engine.js';
+export type { AuditEntry, AuditLog, OperationsLog } from './audit.js';
+export { InMemoryAuditLog, FileOperationsLog, AUDIT_FILE, AUDIT_BASENAME, DEFAULT_COMPACT_BYTES } from './audit.js';
+export type { StorageAdapter } from './storage-adapter.js';
+export { MemoryAdapter } from './memory-adapter.js';
+export type { TransportAdapter, TransportConfig } from './transport-adapter.js';
+export { createGraphApi } from './factory.js';
+export type { GraphApiConfig } from './factory.js';
+export { SE_DESCRIPTOR, projectToOntologyGraph } from './se-descriptor.js';
+export { findRoot } from './find-root.js';
+export type { RootQueryGraph } from './find-root.js';
+export { applyEdgeOps, updateEdge, mergeNodes } from './edge-ops.js';
+export type { EdgeIdentity, UpdateEdgeSet, UpdateEdgeResult, MergeNodesResult, EdgeOp, } from './edge-ops.js';

package/dist/index.js

@@ -0,0 +1,27 @@
+/**
+ * @sigloch/graph-api-core
+ * Framework-agnostic graph operations library with pluggable adapters.
+ * One contract (Zod), one operations layer (GraphService), N adapters.
+ *
+ * @author andreas@siglochconsulting
+ */
+// Trace legality — the ONE checker (CR-GC-247). validPairs is menu-only now.
+export { isValidTrace, tracePatternsOf } from './types.js';
+// Schemas (Zod)
+export { GraphNodeSchema, GraphEdgeSchema, GraphSchema, GraphScopeSchema, GraphQuerySchema, MutationResultSchema, HealthStatusSchema, } from './schemas.js';
+// Service
+export { GraphService } from './graph-service.js';
+// Format E Codec
+export { FormatECodec } from './format-e-codec.js';
+export { DefaultRuleEngine } from './rule-engine.js';
+export { InMemoryAuditLog, FileOperationsLog, AUDIT_FILE, AUDIT_BASENAME, DEFAULT_COMPACT_BYTES } from './audit.js';
+export { MemoryAdapter } from './memory-adapter.js';
+// Factory
+export { createGraphApi } from './factory.js';
+// SE OntologyDescriptor (derived from @sigloch/contracts/se) [CR-195a]
+export { SE_DESCRIPTOR, projectToOntologyGraph } from './se-descriptor.js';
+// Root-Suche — strukturelle Wurzel (SYS ohne eingehende compose), statt UID-Hardcode
+export { findRoot } from './find-root.js';
+// Edge ops — update-edge (flip/retype) + merge-nodes, shared by GraphService.mutate()
+// and the graphcode Apply-Gate (CR-198)
+export { applyEdgeOps, updateEdge, mergeNodes } from './edge-ops.js';

package/dist/memory-adapter.d.ts

@@ -0,0 +1,28 @@
+/**
+ * In-memory StorageAdapter — for tests, CLI, short-lived sessions.
+ */
+import type { StorageAdapter } from './storage-adapter.js';
+import type { GraphNode, GraphEdge, Graph, GraphScope } from './types.js';
+export declare class MemoryAdapter implements StorageAdapter {
+    readonly name = "memory";
+    private nodes;
+    private edges;
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    loadGraph(_scope: GraphScope): Promise<Graph>;
+    saveNodes(nodes: GraphNode[]): Promise<void>;
+    deleteNodes(uids: string[]): Promise<void>;
+    saveEdges(edges: GraphEdge[]): Promise<void>;
+    deleteEdges(keys: Array<{
+        sourceId: string;
+        targetId: string;
+        edgeType: string;
+    }>): Promise<void>;
+    getNode(uid: string): Promise<GraphNode | null>;
+    getSubgraph(root: string, depth: number): Promise<Graph>;
+    stats(): Promise<{
+        nodeCount: number;
+        edgeCount: number;
+    }>;
+    isHealthy(): Promise<boolean>;
+}