@grafema/core 0.1.0-alpha.5 → 0.2.0-beta

package/src/schema/GraphSchemaExtractor.ts

@@ -0,0 +1,177 @@
+/**
+ * GraphSchemaExtractor - Extracts graph node/edge type schemas
+ *
+ * Usage:
+ *   const extractor = new GraphSchemaExtractor(backend);
+ *   const schema = await extractor.extract();
+ *
+ * When to use:
+ *   - Export graph schema for contract tracking
+ *   - Track node/edge type changes via checksum
+ *   - Generate graph documentation
+ */
+
+import { createHash } from 'crypto';
+import { NODE_TYPE, NAMESPACED_TYPE, EDGE_TYPE } from '@grafema/types';
+import type { RFDBServerBackend } from '../storage/backends/RFDBServerBackend.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface NodeTypeSchema {
+  category: 'base' | 'namespaced';
+  namespace?: string;
+  count: number;
+}
+
+export interface EdgeTypeSchema {
+  count: number;
+}
+
+export interface GraphSchema {
+  $schema: 'grafema-graph-v1';
+  extractedAt: string;
+  nodeTypes: Record<string, NodeTypeSchema>;
+  edgeTypes: Record<string, EdgeTypeSchema>;
+  statistics: {
+    totalNodes: number;
+    totalEdges: number;
+    nodeTypeCount: number;
+    edgeTypeCount: number;
+  };
+  checksum: string;
+}
+
+// ============================================================================
+// Extractor
+// ============================================================================
+
+export interface GraphExtractOptions {
+  /** Include all defined types, not just used ones (default: false) */
+  includeAll?: boolean;
+}
+
+export class GraphSchemaExtractor {
+  constructor(private backend: RFDBServerBackend) {}
+
+  /**
+   * Extract graph schema from current database
+   *
+   * @param options.includeAll - If true, include all defined types even with count=0
+   */
+  async extract(options?: GraphExtractOptions): Promise<GraphSchema> {
+    const includeAll = options?.includeAll ?? false;
+    // Get actual counts from graph
+    const nodeCounts = await this.backend.countNodesByType();
+    const edgeCounts = await this.backend.countEdgesByType();
+
+    // Build node types from definitions + counts
+    const nodeTypes: Record<string, NodeTypeSchema> = {};
+
+    // Base node types
+    for (const [_key, value] of Object.entries(NODE_TYPE)) {
+      nodeTypes[value] = {
+        category: 'base',
+        count: nodeCounts[value] || 0,
+      };
+    }
+
+    // Namespaced node types
+    for (const [_key, value] of Object.entries(NAMESPACED_TYPE)) {
+      const namespace = value.split(':')[0];
+      nodeTypes[value] = {
+        category: 'namespaced',
+        namespace,
+        count: nodeCounts[value] || 0,
+      };
+    }
+
+    // Add any additional types found in the graph but not in definitions
+    for (const [type, count] of Object.entries(nodeCounts)) {
+      if (!nodeTypes[type]) {
+        const namespace = type.includes(':') ? type.split(':')[0] : undefined;
+        nodeTypes[type] = {
+          category: namespace ? 'namespaced' : 'base',
+          namespace,
+          count,
+        };
+      }
+    }
+
+    // Build edge types from definitions + counts
+    const edgeTypes: Record<string, EdgeTypeSchema> = {};
+
+    for (const [_key, value] of Object.entries(EDGE_TYPE)) {
+      edgeTypes[value] = {
+        count: edgeCounts[value] || 0,
+      };
+    }
+
+    // Add any additional edge types found in the graph
+    for (const [type, count] of Object.entries(edgeCounts)) {
+      if (!edgeTypes[type]) {
+        edgeTypes[type] = { count };
+      }
+    }
+
+    // Calculate totals
+    const totalNodes = Object.values(nodeCounts).reduce((sum, n) => sum + n, 0);
+    const totalEdges = Object.values(edgeCounts).reduce((sum, n) => sum + n, 0);
+
+    // Filter out types with count=0 unless includeAll is true
+    const filteredNodeTypes: Record<string, NodeTypeSchema> = {};
+    for (const [type, info] of Object.entries(nodeTypes)) {
+      if (includeAll || info.count > 0) {
+        filteredNodeTypes[type] = info;
+      }
+    }
+
+    const filteredEdgeTypes: Record<string, EdgeTypeSchema> = {};
+    for (const [type, info] of Object.entries(edgeTypes)) {
+      if (includeAll || info.count > 0) {
+        filteredEdgeTypes[type] = info;
+      }
+    }
+
+    // Sort for deterministic output
+    const sortedNodeTypes = this.sortObject(filteredNodeTypes);
+    const sortedEdgeTypes = this.sortObject(filteredEdgeTypes);
+
+    // Compute checksum from normalized content (based on filtered types)
+    const checksumContent = {
+      nodeTypes: Object.keys(sortedNodeTypes).sort(),
+      edgeTypes: Object.keys(sortedEdgeTypes).sort(),
+    };
+
+    const checksum = createHash('sha256')
+      .update(JSON.stringify(checksumContent))
+      .digest('hex');
+
+    return {
+      $schema: 'grafema-graph-v1',
+      extractedAt: new Date().toISOString(),
+      nodeTypes: sortedNodeTypes,
+      edgeTypes: sortedEdgeTypes,
+      statistics: {
+        totalNodes,
+        totalEdges,
+        nodeTypeCount: Object.keys(sortedNodeTypes).length,
+        edgeTypeCount: Object.keys(sortedEdgeTypes).length,
+      },
+      checksum: `sha256:${checksum}`,
+    };
+  }
+
+  /**
+   * Sort object keys alphabetically for deterministic output
+   */
+  private sortObject<T>(obj: Record<string, T>): Record<string, T> {
+    const sorted: Record<string, T> = {};
+    const keys = Object.keys(obj).sort();
+    for (const key of keys) {
+      sorted[key] = obj[key];
+    }
+    return sorted;
+  }
+}

package/src/schema/InterfaceSchemaExtractor.ts

@@ -0,0 +1,173 @@
+/**
+ * InterfaceSchemaExtractor - Extracts interface schemas from graph
+ *
+ * Usage:
+ *   const extractor = new InterfaceSchemaExtractor(backend);
+ *   const schema = await extractor.extract('ConfigSchema');
+ *
+ * When to use:
+ *   - Export interface contracts for documentation
+ *   - Track interface changes via checksum
+ *   - Generate API documentation from graph
+ */
+
+import { createHash } from 'crypto';
+import type { RFDBServerBackend } from '../storage/backends/RFDBServerBackend.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface PropertySchema {
+  type: string;
+  required: boolean;
+  readonly: boolean;
+}
+
+export interface InterfaceSchema {
+  $schema: 'grafema-interface-v1';
+  name: string;
+  source: {
+    file: string;
+    line: number;
+    column: number;
+  };
+  typeParameters?: string[];
+  properties: Record<string, PropertySchema>;
+  extends: string[];
+  checksum: string;
+}
+
+export interface ExtractOptions {
+  /** Specific file path if multiple interfaces have same name */
+  file?: string;
+}
+
+export interface InterfaceNodeRecord {
+  id: string;
+  type: 'INTERFACE';
+  name: string;
+  file: string;
+  line: number;
+  column: number;
+  extends: string[];
+  properties: Array<{
+    name: string;
+    type?: string;
+    optional?: boolean;
+    readonly?: boolean;
+  }>;
+  typeParameters?: string[];
+}
+
+// ============================================================================
+// Extractor
+// ============================================================================
+
+export class InterfaceSchemaExtractor {
+  constructor(private backend: RFDBServerBackend) {}
+
+  /**
+   * Extract schema for interface by name
+   *
+   * @param interfaceName - Name of the interface (e.g., 'ConfigSchema')
+   * @param options - Optional filters
+   * @returns InterfaceSchema or null if not found
+   * @throws Error if multiple interfaces match and no file specified
+   */
+  async extract(interfaceName: string, options?: ExtractOptions): Promise<InterfaceSchema | null> {
+    const interfaces = await this.findInterfaces(interfaceName);
+
+    if (interfaces.length === 0) {
+      return null;
+    }
+
+    // Filter by file if specified
+    let match: InterfaceNodeRecord;
+    if (options?.file) {
+      const fileFilter = options.file;
+      const filtered = interfaces.filter(i => i.file === fileFilter || i.file.endsWith(fileFilter));
+      if (filtered.length === 0) {
+        return null;
+      }
+      match = filtered[0];
+    } else if (interfaces.length > 1) {
+      const locations = interfaces.map(i => `  - ${i.file}:${i.line}`).join('\n');
+      throw new Error(
+        `Multiple interfaces named "${interfaceName}" found:\n${locations}\n` +
+        `Use --file option to specify which one.`
+      );
+    } else {
+      match = interfaces[0];
+    }
+
+    return this.buildSchema(match);
+  }
+
+  /**
+   * Find all interfaces with given name
+   */
+  async findInterfaces(name: string): Promise<InterfaceNodeRecord[]> {
+    const result: InterfaceNodeRecord[] = [];
+
+    for await (const node of this.backend.queryNodes({ nodeType: 'INTERFACE' })) {
+      if (node.name === name) {
+        result.push(node as unknown as InterfaceNodeRecord);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Build InterfaceSchema from node record
+   */
+  private buildSchema(node: InterfaceNodeRecord): InterfaceSchema {
+    // Sort properties alphabetically for deterministic output
+    const sortedProperties = [...(node.properties || [])].sort((a, b) =>
+      a.name.localeCompare(b.name)
+    );
+
+    const properties: Record<string, PropertySchema> = {};
+    for (const prop of sortedProperties) {
+      properties[prop.name] = {
+        type: prop.type || 'unknown',
+        required: !prop.optional,
+        readonly: prop.readonly || false
+      };
+    }
+
+    // Compute checksum from normalized content
+    const checksumContent = {
+      name: node.name,
+      properties: sortedProperties.map(p => ({
+        name: p.name,
+        type: p.type,
+        optional: p.optional,
+        readonly: p.readonly
+      })),
+      extends: [...(node.extends || [])].sort(),
+      typeParameters: node.typeParameters
+    };
+
+    const checksum = createHash('sha256')
+      .update(JSON.stringify(checksumContent))
+      .digest('hex');
+
+    return {
+      $schema: 'grafema-interface-v1',
+      name: node.name,
+      source: {
+        file: node.file,
+        line: node.line,
+        column: node.column
+      },
+      ...(node.typeParameters && node.typeParameters.length > 0 && {
+        typeParameters: node.typeParameters
+      }),
+      properties,
+      extends: node.extends || [],
+      checksum: `sha256:${checksum}`
+    };
+  }
+}

package/src/schema/index.ts

@@ -0,0 +1,5 @@
+export { InterfaceSchemaExtractor } from './InterfaceSchemaExtractor.js';
+export type { InterfaceSchema, PropertySchema, ExtractOptions } from './InterfaceSchemaExtractor.js';
+
+export { GraphSchemaExtractor } from './GraphSchemaExtractor.js';
+export type { GraphSchema, NodeTypeSchema, EdgeTypeSchema, GraphExtractOptions } from './GraphSchemaExtractor.js';

package/src/storage/backends/RFDBServerBackend.ts

@@ -23,10 +23,12 @@ import { existsSync, unlinkSync } from 'fs';
 import { spawn, type ChildProcess } from 'child_process';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
 import { setTimeout as sleep } from 'timers/promises';
 
 import type { WireNode, WireEdge } from '@grafema/types';
 import type { NodeType, EdgeType } from '@grafema/types';
+import type { BaseNodeRecord, EdgeRecord } from '@grafema/types';
 import type { AttrQuery, GraphStats, GraphExport } from '../../core/GraphBackend.js';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -40,30 +42,6 @@ export interface RFDBServerBackendOptions {
   dbPath?: string;
 }
 
-/**
- * Node as returned from the backend
- */
-export interface BackendNode {
-  id: string;
-  type: string;
-  nodeType: string;
-  name: string;
-  file: string;
-  exported: boolean;
-  [key: string]: unknown;
-}
-
-/**
- * Edge as returned from the backend
- */
-export interface BackendEdge {
-  src: string;
-  dst: string;
-  type: string;
-  edgeType: string;
-  [key: string]: unknown;
-}
-
 /**
  * Input node format (flexible)
  */
@@ -176,13 +154,29 @@ export class RFDBServerBackend {
 
   /**
    * Find RFDB server binary in order of preference:
-   * 1. @grafema/rfdb npm package
-   * 2. rust-engine/target/release (monorepo development)
-   * 3. rust-engine/target/debug
+   * 1. packages/rfdb-server/target/release (monorepo development - prioritized for dev)
+   * 2. packages/rfdb-server/target/debug
+   * 3. @grafema/rfdb npm package (fallback for production)
    */
   private _findServerBinary(): string | null {
-    // 1. Check @grafema/rfdb npm package
+    // 1. Check packages/rfdb-server in monorepo (prioritized for development)
+    const projectRoot = join(__dirname, '../../../../..');
+    const releaseBinary = join(projectRoot, 'packages/rfdb-server/target/release/rfdb-server');
+    if (existsSync(releaseBinary)) {
+      console.log(`[RFDBServerBackend] Found release binary: ${releaseBinary}`);
+      return releaseBinary;
+    }
+
+    // 2. Check debug build
+    const debugBinary = join(projectRoot, 'packages/rfdb-server/target/debug/rfdb-server');
+    if (existsSync(debugBinary)) {
+      console.log(`[RFDBServerBackend] Found debug binary: ${debugBinary}`);
+      return debugBinary;
+    }
+
+    // 3. Check @grafema/rfdb npm package (fallback)
     try {
+      const require = createRequire(import.meta.url);
       const rfdbPkg = require.resolve('@grafema/rfdb');
       const rfdbDir = dirname(rfdbPkg);
       const platform = process.platform;
@@ -206,21 +200,6 @@ export class RFDBServerBackend {
       // @grafema/rfdb not installed
     }
 
-    // 2. Check rust-engine in monorepo
-    const projectRoot = join(__dirname, '../../../../..');
-    const releaseBinary = join(projectRoot, 'rust-engine/target/release/rfdb-server');
-    if (existsSync(releaseBinary)) {
-      console.log(`[RFDBServerBackend] Found release binary: ${releaseBinary}`);
-      return releaseBinary;
-    }
-
-    // 3. Check debug build
-    const debugBinary = join(projectRoot, 'rust-engine/target/debug/rfdb-server');
-    if (existsSync(debugBinary)) {
-      console.log(`[RFDBServerBackend] Found debug binary: ${debugBinary}`);
-      return debugBinary;
-    }
-
     return null;
   }
 
@@ -283,20 +262,26 @@ export class RFDBServerBackend {
   }
 
   /**
-   * Close connection and stop server if we started it
+   * Close client connection. Server continues running to serve other clients.
    */
   async close(): Promise<void> {
+    // Request server flush before disconnecting
     if (this.client) {
+      try {
+        await this.client.flush();
+      } catch {
+        // Ignore flush errors on close - best effort
+      }
       await this.client.close();
       this.client = null;
     }
     this.connected = false;
 
-    // Kill server process if we started it
-    if (this.serverProcess) {
-      this.serverProcess.kill('SIGTERM');
-      this.serverProcess = null;
-    }
+    // NOTE: We intentionally do NOT kill the server process.
+    // The server continues running to serve other clients (MCP, other CLI invocations).
+    // This is by design for multi-client architecture.
+    // Server lifecycle is managed separately (system process, or manual grafema server stop).
+    this.serverProcess = null;
   }
 
   /**
@@ -371,14 +356,22 @@ export class RFDBServerBackend {
     }
 
     const wireEdges: WireEdge[] = edges.map(e => {
-      const { src, dst, type, edgeType, edge_type, etype, ...rest } = e;
+      const { src, dst, type, edgeType, edge_type, etype, metadata, ...rest } = e;
+
+      // Flatten metadata: spread both edge-level properties and nested metadata
+      const flatMetadata = {
+        _origSrc: String(src),
+        _origDst: String(dst),
+        ...rest,
+        ...(typeof metadata === 'object' && metadata !== null ? metadata : {})
+      };
 
       return {
         src: String(src),
         dst: String(dst),
         edgeType: (edgeType || edge_type || etype || type || 'UNKNOWN') as EdgeType,
-        // Store original string IDs in metadata for retrieval
-        metadata: JSON.stringify({ _origSrc: String(src), _origDst: String(dst), ...rest }),
+        // Store flattened metadata for retrieval
+        metadata: JSON.stringify(flatMetadata),
       };
     });
 
@@ -388,7 +381,7 @@ export class RFDBServerBackend {
   /**
    * Get a node by ID
    */
-  async getNode(id: string): Promise<BackendNode | null> {
+  async getNode(id: string): Promise<BaseNodeRecord | null> {
     if (!this.client) throw new Error('Not connected');
     const node = await this.client.getNode(String(id));
     if (!node) return null;
@@ -423,7 +416,7 @@ export class RFDBServerBackend {
   /**
    * Parse a node from wire format to JS format
    */
-  private _parseNode(wireNode: WireNode): BackendNode {
+  private _parseNode(wireNode: WireNode): BaseNodeRecord {
     const metadata: Record<string, unknown> = wireNode.metadata ? JSON.parse(wireNode.metadata) : {};
 
     // Parse nested JSON strings
@@ -439,21 +432,48 @@ export class RFDBServerBackend {
 
     const humanId = (metadata.originalId as string) || wireNode.id;
 
+    // Exclude standard fields from metadata to prevent overwriting wireNode values
+    // REG-325: Metadata spread was overwriting name with LITERAL node data
+    const {
+      id: _id,
+      type: _type,
+      name: _name,
+      file: _file,
+      exported: _exported,
+      nodeType: _nodeType,
+      originalId: _originalId,  // Already extracted above
+      ...safeMetadata
+    } = metadata;
+
     return {
       id: humanId,
-      nodeType: wireNode.nodeType,
       type: wireNode.nodeType,
       name: wireNode.name,
       file: wireNode.file,
       exported: wireNode.exported,
-      ...metadata,
+      ...safeMetadata,
+    };
+  }
+
+  /**
+   * Parse an edge from wire format to EdgeRecord
+   */
+  private _parseEdge(wireEdge: WireEdge): EdgeRecord {
+    const meta: Record<string, unknown> = wireEdge.metadata ? JSON.parse(wireEdge.metadata) : {};
+    // Use original string IDs if stored, otherwise use wire IDs
+    const { _origSrc, _origDst, ...rest } = meta;
+    return {
+      src: (_origSrc as string) || wireEdge.src,
+      dst: (_origDst as string) || wireEdge.dst,
+      type: wireEdge.edgeType,
+      metadata: Object.keys(rest).length > 0 ? rest : undefined,
     };
   }
 
   /**
    * Async generator for querying nodes
    */
-  async *queryNodes(query: NodeQuery): AsyncGenerator<BackendNode, void, unknown> {
+  async *queryNodes(query: NodeQuery): AsyncGenerator<BaseNodeRecord, void, unknown> {
     if (!this.client) throw new Error('Not connected');
 
     // Build query for server
@@ -482,8 +502,8 @@ export class RFDBServerBackend {
   /**
    * Get ALL nodes matching query (collects from queryNodes into array)
    */
-  async getAllNodes(query: NodeQuery = {}): Promise<BackendNode[]> {
-    const nodes: BackendNode[] = [];
+  async getAllNodes(query: NodeQuery = {}): Promise<BaseNodeRecord[]> {
+    const nodes: BaseNodeRecord[] = [];
     for await (const node of this.queryNodes(query)) {
       nodes.push(node);
     }
@@ -505,66 +525,35 @@ export class RFDBServerBackend {
   /**
    * Get all edges
    */
-  async getAllEdges(): Promise<BackendEdge[]> {
+  async getAllEdges(): Promise<EdgeRecord[]> {
     return this.getAllEdgesAsync();
   }
 
   /**
    * Get all edges (async version)
    */
-  async getAllEdgesAsync(): Promise<BackendEdge[]> {
+  async getAllEdgesAsync(): Promise<EdgeRecord[]> {
     if (!this.client) throw new Error('Not connected');
     const edges = await this.client.getAllEdges();
-    return edges.map(e => {
-      const meta = JSON.parse(e.metadata || '{}');
-      // Use original string IDs if stored, otherwise use numeric IDs
-      const { _origSrc, _origDst, ...rest } = meta;
-      return {
-        src: _origSrc || e.src,
-        dst: _origDst || e.dst,
-        type: e.edgeType,
-        edgeType: e.edgeType,
-        ...rest,
-      };
-    });
+    return edges.map(e => this._parseEdge(e));
   }
 
   /**
    * Get outgoing edges from a node
    */
-  async getOutgoingEdges(nodeId: string, edgeTypes: EdgeType[] | null = null): Promise<BackendEdge[]> {
+  async getOutgoingEdges(nodeId: string, edgeTypes: EdgeType[] | null = null): Promise<EdgeRecord[]> {
     if (!this.client) throw new Error('Not connected');
     const edges = await this.client.getOutgoingEdges(nodeId, edgeTypes || undefined);
-    return edges.map(e => {
-      const meta = JSON.parse(e.metadata || '{}');
-      const { _origSrc, _origDst, ...rest } = meta;
-      return {
-        src: _origSrc || e.src,
-        dst: _origDst || e.dst,
-        type: e.edgeType,
-        edgeType: e.edgeType,
-        ...rest,
-      };
-    });
+    return edges.map(e => this._parseEdge(e));
   }
 
   /**
    * Get incoming edges to a node
    */
-  async getIncomingEdges(nodeId: string, edgeTypes: EdgeType[] | null = null): Promise<BackendEdge[]> {
+  async getIncomingEdges(nodeId: string, edgeTypes: EdgeType[] | null = null): Promise<EdgeRecord[]> {
     if (!this.client) throw new Error('Not connected');
     const edges = await this.client.getIncomingEdges(nodeId, edgeTypes || undefined);
-    return edges.map(e => {
-      const meta = JSON.parse(e.metadata || '{}');
-      const { _origSrc, _origDst, ...rest } = meta;
-      return {
-        src: _origSrc || e.src,
-        dst: _origDst || e.dst,
-        type: e.edgeType,
-        edgeType: e.edgeType,
-        ...rest,
-      };
-    });
+    return edges.map(e => this._parseEdge(e));
   }
 
   // ===========================================================================
@@ -587,6 +576,19 @@ export class RFDBServerBackend {
     return this.client.dfs(startIds, maxDepth, edgeTypes);
   }
 
+  /**
+   * Reachability query - find all nodes reachable from start nodes
+   */
+  async reachability(
+    startIds: string[],
+    maxDepth: number,
+    edgeTypes: EdgeType[] = [],
+    backward: boolean = false
+  ): Promise<string[]> {
+    if (!this.client) throw new Error('Not connected');
+    return this.client.reachability(startIds, maxDepth, edgeTypes, backward);
+  }
+
   // ===========================================================================
   // Statistics
   // ===========================================================================
@@ -713,7 +715,7 @@ export class RFDBServerBackend {
   /**
    * Find nodes by predicate (for compatibility)
    */
-  async findNodes(predicate: (node: BackendNode) => boolean): Promise<BackendNode[]> {
+  async findNodes(predicate: (node: BaseNodeRecord) => boolean): Promise<BaseNodeRecord[]> {
     const allNodes = await this.getAllNodes();
     return allNodes.filter(predicate);
   }

package/src/storage/backends/typeValidation.ts

@@ -45,6 +45,7 @@ const KNOWN_EDGE_TYPES = new Set<string>([
   'INTERACTS_WITH', 'CALLS_API', 'LISTENS_TO', 'JOINS_ROOM', 'EMITS_EVENT',
   'RETURNS', 'RECEIVES_ARGUMENT', 'READS_FROM', 'THROWS', 'REGISTERS_VIEW',
   'GOVERNS', 'VIOLATES', 'HAS_PARAMETER', 'DERIVES_FROM',
+  'RESOLVES_TO',  // Promise resolve() data flow
 ]);
 
 // Store initial edge types for reset