@grafema/core 0.2.11 → 0.2.12-beta

package/src/ParallelAnalysisRunner.ts

@@ -9,17 +9,17 @@
  * - Barrier: wait for all tasks before returning
  */
 
-import { existsSync, unlinkSync } from 'fs';
+import { existsSync } from 'fs';
 import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
 import type { ChildProcess } from 'child_process';
-import { spawn, execSync } from 'child_process';
 import { setTimeout as sleep } from 'timers/promises';
 import { AnalysisQueue } from './core/AnalysisQueue.js';
 import type { Plugin } from './plugins/Plugin.js';
 import type { GraphBackend, Logger } from '@grafema/types';
 import type { ProgressCallback } from './PhaseRunner.js';
 import type { ParallelConfig, DiscoveryManifest } from './OrchestratorTypes.js';
+import { findRfdbBinary } from './utils/findRfdbBinary.js';
+import { startRfdbServer } from './utils/startRfdbServer.js';
 
 export class ParallelAnalysisRunner {
   private analysisQueue: AnalysisQueue | null = null;
@@ -43,10 +43,9 @@ export class ParallelAnalysisRunner {
    * - Barrier waits for all tasks before ENRICHMENT phase
    */
   async run(manifest: DiscoveryManifest): Promise<void> {
-    const socketPath = this.parallelConfig.socketPath || '/tmp/rfdb.sock';
-    const maxWorkers = this.parallelConfig.maxWorkers || null;
-
     const mainDbPath = (this.graph as unknown as { dbPath?: string }).dbPath || join(manifest.projectPath, '.grafema', 'graph.rfdb');
+    const socketPath = this.parallelConfig.socketPath || join(dirname(mainDbPath), 'rfdb.sock');
+    const maxWorkers = this.parallelConfig.maxWorkers || null;
 
     this.logger.debug('Starting queue-based parallel analysis', { database: mainDbPath });
 
@@ -67,6 +66,20 @@ export class ParallelAnalysisRunner {
     await this.analysisQueue.start();
 
     let moduleCount = 0;
+    let completedCount = 0;
+
+    this.analysisQueue.on('taskCompleted', ({ file, stats, duration }: { file: string; stats?: { nodes?: number }; duration: number }) => {
+      completedCount++;
+      this.onProgress({
+        phase: 'analysis',
+        currentPlugin: 'AnalysisQueue',
+        message: `${file.split('/').pop()} (${stats?.nodes || 0} nodes, ${duration}ms)`,
+        totalFiles: moduleCount,
+        processedFiles: completedCount,
+        currentService: file,
+      });
+    });
+
     for await (const node of this.graph.queryNodes({ type: 'MODULE' })) {
       if (!node.file?.match(/\.(js|jsx|ts|tsx|mjs|cjs)$/)) continue;
 
@@ -81,14 +94,6 @@ export class ParallelAnalysisRunner {
 
     this.logger.debug('Queued modules for analysis', { count: moduleCount });
 
-    this.analysisQueue.on('taskCompleted', ({ file, stats, duration }: { file: string; stats?: { nodes?: number }; duration: number }) => {
-      this.onProgress({
-        phase: 'analysis',
-        currentPlugin: 'AnalysisQueue',
-        message: `${file.split('/').pop()} (${stats?.nodes || 0} nodes, ${duration}ms)`,
-      });
-    });
-
     this.analysisQueue.on('taskFailed', ({ file, error }: { file: string; error: string }) => {
       this.logger.error('Analysis failed', { file, error });
     });
@@ -111,6 +116,7 @@ export class ParallelAnalysisRunner {
    * Start RFDB server process (or connect to existing one).
    */
   private async startRfdbServer(socketPath: string, dbPath: string): Promise<void> {
+    // Check if server is already running
     if (existsSync(socketPath)) {
       try {
         const { RFDBClient } = await import('@grafema/rfdb-client');
@@ -123,49 +129,25 @@ export class ParallelAnalysisRunner {
         this._serverWasExternal = true;
         return;
       } catch {
-        this.logger.debug('Stale socket found, removing');
-        unlinkSync(socketPath);
+        this.logger.debug('Stale socket found, will be removed by startRfdbServer');
       }
     }
 
-    const projectRoot = join(dirname(fileURLToPath(import.meta.url)), '../..');
-    const serverBinary = join(projectRoot, 'packages/rfdb-server/target/release/rfdb-server');
-    const debugBinary = join(projectRoot, 'packages/rfdb-server/target/debug/rfdb-server');
-
-    let binaryPath = existsSync(serverBinary) ? serverBinary : debugBinary;
-
-    if (!existsSync(binaryPath)) {
-      this.logger.debug('RFDB server binary not found, building', { path: binaryPath });
-      execSync('cargo build --bin rfdb-server', {
-        cwd: join(projectRoot, 'packages/rfdb-server'),
-        stdio: 'inherit',
-      });
-      binaryPath = debugBinary;
+    const binaryPath = findRfdbBinary();
+    if (!binaryPath) {
+      throw new Error('RFDB server binary not found');
     }
 
     this.logger.debug('Starting RFDB server', { binary: binaryPath, database: dbPath });
-    this.rfdbServerProcess = spawn(binaryPath, [dbPath, '--socket', socketPath], {
-      stdio: ['ignore', 'pipe', 'pipe'],
+    this.rfdbServerProcess = await startRfdbServer({
+      dbPath,
+      socketPath,
+      binaryPath,
+      waitTimeoutMs: 3000,
+      logger: { debug: (m: string) => this.logger.debug(m) },
     });
     this._serverWasExternal = false;
 
-    this.rfdbServerProcess.stderr?.on('data', (data: Buffer) => {
-      const msg = data.toString().trim();
-      if (!msg.includes('FLUSH') && !msg.includes('WRITER')) {
-        this.logger.debug('rfdb-server', { message: msg });
-      }
-    });
-
-    let attempts = 0;
-    while (!existsSync(socketPath) && attempts < 30) {
-      await sleep(100);
-      attempts++;
-    }
-
-    if (!existsSync(socketPath)) {
-      throw new Error('RFDB server failed to start');
-    }
-
     this.logger.debug('RFDB server started', { socketPath });
   }
 

package/src/PhaseRunner.ts

@@ -50,6 +50,8 @@ export interface PhaseRunnerDeps {
   resourceRegistry: ResourceRegistry;
   configServices?: ServiceDefinition[];
   routing?: RoutingRule[];
+  /** When true, commitBatch defers index rebuild for bulk load (REG-487). */
+  deferIndexing?: boolean;
 }
 
 export class PhaseRunner {
@@ -92,7 +94,9 @@ export class PhaseRunner {
     graph.beginBatch();
     try {
       const result = await plugin.execute(pluginContext);
-      const delta = await graph.commitBatch(tags);
+      const deferIndex = pluginContext.deferIndexing ?? false;
+      const protectedTypes = phaseName === 'ANALYSIS' ? ['MODULE'] : undefined;
+      const delta = await graph.commitBatch(tags, deferIndex, protectedTypes);
       return { result, delta };
     } catch (error) {
       graph.abortBatch();
@@ -121,6 +125,8 @@ export class PhaseRunner {
       rootPrefix: (baseContext as { rootPrefix?: string }).rootPrefix,
       // REG-256: Pass resource registry for inter-plugin communication
       resources: resourceRegistry,
+      // REG-487: Pass deferIndexing flag for bulk load optimization
+      deferIndexing: this.deps.deferIndexing ?? false,
     };
 
     // REG-256: Ensure config is available with routing and services for all plugins

package/src/core/IncrementalReanalyzer.ts

@@ -25,9 +25,9 @@ export interface ReanalysisOptions {
 
 export interface ReanalysisProgress {
   phase: 'clearing' | 'indexing' | 'analysis' | 'enrichment';
-  current: number;
-  total: number;
-  currentFile?: string;
+  processedFiles: number;
+  totalFiles: number;
+  currentService?: string;
 }
 
 export interface ReanalysisResult {
@@ -78,9 +78,9 @@ export class IncrementalReanalyzer {
       if (options.onProgress) {
         options.onProgress({
           phase: 'clearing',
-          current: i + 1,
-          total: staleModules.length,
-          currentFile: module.file
+          processedFiles: i + 1,
+          totalFiles: staleModules.length,
+          currentService: module.file
         });
       }
       const cleared = await clearFileNodesIfNeeded(this.graph, module.file, touchedFiles);
@@ -98,9 +98,9 @@ export class IncrementalReanalyzer {
       if (options.onProgress) {
         options.onProgress({
           phase: 'indexing',
-          current: i + 1,
-          total: modifiedModules.length,
-          currentFile: module.file
+          processedFiles: i + 1,
+          totalFiles: modifiedModules.length,
+          currentService: module.file
         });
       }
 
@@ -127,9 +127,9 @@ export class IncrementalReanalyzer {
       if (options.onProgress) {
         options.onProgress({
           phase: 'analysis',
-          current: i + 1,
-          total: modulesToAnalyze.length,
-          currentFile: module.file
+          processedFiles: i + 1,
+          totalFiles: modulesToAnalyze.length,
+          currentService: module.file
         });
       }
 
@@ -150,7 +150,7 @@ export class IncrementalReanalyzer {
     // STEP 4: Re-run enrichment plugins
     if (!options.skipEnrichment && modulesToAnalyze.length > 0) {
       if (options.onProgress) {
-        options.onProgress({ phase: 'enrichment', current: 0, total: 2 });
+        options.onProgress({ phase: 'enrichment', processedFiles: 0, totalFiles: 2 });
       }
 
       const pluginContext: PluginContext = {
@@ -169,7 +169,7 @@ export class IncrementalReanalyzer {
       }
 
       if (options.onProgress) {
-        options.onProgress({ phase: 'enrichment', current: 1, total: 2 });
+        options.onProgress({ phase: 'enrichment', processedFiles: 1, totalFiles: 2 });
       }
 
       const importExportLinker = new ImportExportLinker();
@@ -182,7 +182,7 @@ export class IncrementalReanalyzer {
       }
 
       if (options.onProgress) {
-        options.onProgress({ phase: 'enrichment', current: 2, total: 2 });
+        options.onProgress({ phase: 'enrichment', processedFiles: 2, totalFiles: 2 });
       }
     }
 

package/src/index.ts

@@ -129,6 +129,10 @@ export { calculateFileHash, calculateFileHashAsync, calculateContentHash } from
 export { findRfdbBinary, getBinaryNotFoundMessage, getPlatformDir } from './utils/findRfdbBinary.js';
 export type { FindBinaryOptions } from './utils/findRfdbBinary.js';
 
+// RFDB server lifecycle (RFD-40)
+export { startRfdbServer } from './utils/startRfdbServer.js';
+export type { StartRfdbServerOptions } from './utils/startRfdbServer.js';
+
 // Module resolution utilities (REG-320)
 export {
   resolveModulePath,

package/src/plugins/analysis/JSASTAnalyzer.ts

@@ -383,14 +383,21 @@ export class JSASTAnalyzer extends Plugin {
       const queue = new PriorityQueue();
       const pool = new WorkerPool(context.workerCount || 10);
 
+      const deferIndex = context.deferIndexing ?? false;
+
       pool.registerHandler('ANALYZE_MODULE', async (task) => {
         // Per-module batch: commit after each module to avoid buffering the entire
         // graph in memory. Prevents connection timeouts on large codebases.
+        // REG-487: Pass deferIndex to skip per-commit index rebuild during bulk load.
         if (graph.beginBatch && graph.commitBatch) {
           graph.beginBatch();
           try {
             const result = await this.analyzeModule(task.data.module, graph, projectPath);
-            await graph.commitBatch(['JSASTAnalyzer', 'ANALYSIS', task.data.module.file]);
+            await graph.commitBatch(
+              ['JSASTAnalyzer', 'ANALYSIS', task.data.module.file],
+              deferIndex,
+              ['MODULE'],
+            );
             return result;
           } catch (err) {
             if (graph.abortBatch) graph.abortBatch();
@@ -422,7 +429,8 @@ export class JSASTAnalyzer extends Plugin {
             currentPlugin: 'JSASTAnalyzer',
             message: `Analyzing ${currentFile} (${completed}/${modulesToAnalyze.length})`,
             totalFiles: modulesToAnalyze.length,
-            processedFiles: completed
+            processedFiles: completed,
+            currentService: currentFile
           });
         }
       }, 500);
@@ -443,6 +451,14 @@ export class JSASTAnalyzer extends Plugin {
 
       clearInterval(progressInterval);
 
+      // REG-487: Rebuild indexes after all deferred commits.
+      // This runs inside JSASTAnalyzer.execute() so downstream ANALYSIS plugins
+      // (which depend on JSASTAnalyzer) see rebuilt indexes.
+      if (deferIndex && graph.rebuildIndexes) {
+        logger.info('Rebuilding indexes after deferred bulk load...');
+        await graph.rebuildIndexes();
+      }
+
       if (context.onProgress) {
         context.onProgress({
           phase: 'analysis',
@@ -557,7 +573,8 @@ export class JSASTAnalyzer extends Plugin {
             currentPlugin: 'JSASTAnalyzer',
             message: `Processed ${result.module.name}`,
             totalFiles: modules.length,
-            processedFiles: results.indexOf(result) + 1
+            processedFiles: results.indexOf(result) + 1,
+            currentService: result.module.file || result.module.name
           });
         }
       }
@@ -1719,6 +1736,11 @@ export class JSASTAnalyzer extends Plugin {
           if (processedConstructorCalls.has(nodeKey)) {
             return;
           }
+
+          // Skip in-function calls — handled by NewExpressionHandler in analyzeFunctionBody
+          const functionParent = newPath.getFunctionParent();
+          if (functionParent) return;
+
           processedConstructorCalls.add(nodeKey);
 
           // Determine className from callee
@@ -1742,7 +1764,8 @@ export class JSASTAnalyzer extends Plugin {
               isBuiltin,
               file: module.file,
               line,
-              column
+              column,
+              parentScopeId: module.id
             });
 
             // REG-334: If this is Promise constructor with executor callback,

package/src/plugins/analysis/ast/GraphBuilder.ts

@@ -311,6 +311,15 @@ export class GraphBuilder {
         line: constructorCall.line,
         column: constructorCall.column
       } as GraphNode);
+
+      // SCOPE -> CONTAINS -> CONSTRUCTOR_CALL
+      if (constructorCall.parentScopeId) {
+        this._bufferEdge({
+          type: 'CONTAINS',
+          src: constructorCall.parentScopeId,
+          dst: constructorCall.id
+        });
+      }
     }
 
     // Phase 2: Delegate to domain builders

package/src/plugins/analysis/ast/builders/ModuleRuntimeBuilder.ts

@@ -52,7 +52,7 @@ export class ModuleRuntimeBuilder implements DomainBuilder {
 
   private bufferImportNodes(module: ModuleNode, imports: ImportInfo[]): void {
     for (const imp of imports) {
-      const { source, specifiers, line, column, isDynamic, isResolvable, dynamicPath } = imp;
+      const { source, specifiers, line, column, importKind, isDynamic, isResolvable, dynamicPath } = imp;
 
       // REG-273: Handle side-effect-only imports (no specifiers)
       if (specifiers.length === 0) {
@@ -66,7 +66,8 @@ export class ModuleRuntimeBuilder implements DomainBuilder {
           {
             imported: '*',      // no specific export
             local: source,      // source becomes local
-            sideEffect: true    // mark as side-effect import
+            sideEffect: true,   // mark as side-effect import
+            importBinding: importKind || 'value'
           }
         );
 
@@ -110,6 +111,7 @@ export class ModuleRuntimeBuilder implements DomainBuilder {
               imported: spec.imported,
               local: spec.local,
               sideEffect: false,  // regular imports are not side-effects
+              importBinding: spec.importKind === 'type' ? 'type' : (importKind || 'value'),
               // importType is auto-detected from imported field
               // Dynamic import fields
               isDynamic,

package/src/plugins/analysis/ast/handlers/NewExpressionHandler.ts

@@ -47,7 +47,8 @@ export class NewExpressionHandler extends FunctionBodyHandler {
               isBuiltin,
               file: ctx.module.file,
               line,
-              column
+              column,
+              parentScopeId: ctx.getCurrentScopeId()
             });
 
             // REG-334: If this is Promise constructor with executor callback,

package/src/plugins/analysis/ast/types.ts

@@ -338,6 +338,7 @@ export interface ConstructorCallInfo {
   file: string;
   line: number;
   column: number;
+  parentScopeId?: string;
 }
 
 // === CLASS DECLARATION INFO ===
@@ -501,6 +502,7 @@ export interface ImportInfo {
   line: number;
   column?: number;  // Column position for ImportNode
   specifiers: ImportSpecifier[];
+  importKind?: 'value' | 'type' | 'typeof';  // TypeScript: import type { ... }
   isDynamic?: boolean;         // true for dynamic import() expressions
   isResolvable?: boolean;      // true if path is a string literal (statically analyzable)
   dynamicPath?: string;        // original expression for template/variable paths
@@ -509,6 +511,7 @@ export interface ImportInfo {
 export interface ImportSpecifier {
   imported: string;  // имя в экспортируемом модуле (default, *, или имя)
   local: string;     // имя в текущем модуле
+  importKind?: 'value' | 'type' | 'typeof';  // specifier-level: import { type X } from '...'
 }
 
 // === EXPORT INFO ===

package/src/plugins/analysis/ast/visitors/ImportExportVisitor.ts

@@ -41,6 +41,7 @@ export type ExtractVariableNamesCallback = (pattern: Node) => VariableInfo[];
 interface ImportSpecifierInfo {
   imported: string;
   local: string;
+  importKind?: 'value' | 'type' | 'typeof';  // specifier-level: import { type X } from '...'
 }
 
 /**
@@ -51,6 +52,7 @@ interface ImportInfo {
   specifiers: ImportSpecifierInfo[];
   line: number;
   column?: number;
+  importKind?: 'value' | 'type' | 'typeof';  // TypeScript: import type { ... }
   isDynamic?: boolean;         // true for dynamic import() expressions
   isResolvable?: boolean;      // true if path is a string literal (statically analyzable)
   dynamicPath?: string;        // original expression for template/variable paths
@@ -106,13 +108,16 @@ export class ImportExportVisitor extends ASTVisitor {
         node.specifiers.forEach((spec) => {
           if (spec.type === 'ImportSpecifier') {
             // import { foo, bar } from './module'
+            // import { type Foo, bar } from './module' (specifier-level type)
             const importSpec = spec as ImportSpecifier;
             const importedName = importSpec.imported.type === 'Identifier'
               ? importSpec.imported.name
               : importSpec.imported.value;
+            const specKind = (importSpec as ImportSpecifier & { importKind?: string }).importKind;
             specifiers.push({
               imported: importedName,
-              local: importSpec.local.name
+              local: importSpec.local.name,
+              importKind: specKind as ImportSpecifierInfo['importKind']
             });
           } else if (spec.type === 'ImportDefaultSpecifier') {
             // import foo from './module'
@@ -135,7 +140,8 @@ export class ImportExportVisitor extends ASTVisitor {
           source,
           specifiers,
           line: getLine(node),
-          column: getColumn(node)
+          column: getColumn(node),
+          importKind: (node as ImportDeclaration & { importKind?: string }).importKind as ImportInfo['importKind']
         });
       },
 

package/src/plugins/enrichment/ImportExportLinker.ts

@@ -102,20 +102,30 @@ export class ImportExportLinker extends Plugin {
       const currentDir = dirname(imp.file!);
       const basePath = join(currentDir, imp.source!);
 
-      // Try different extensions
+      // Build candidate paths: append extensions + TypeScript .js→.ts redirect
+      const candidates: string[] = [];
       const extensions = ['', '.js', '.ts', '.jsx', '.tsx', '/index.js', '/index.ts'];
+      for (const ext of extensions) {
+        candidates.push(basePath + ext);
+      }
+      // TypeScript convention: imports use .js but actual files are .ts
+      if (basePath.endsWith('.js')) {
+        candidates.push(basePath.slice(0, -3) + '.ts');
+        candidates.push(basePath.slice(0, -3) + '.tsx');
+      } else if (basePath.endsWith('.jsx')) {
+        candidates.push(basePath.slice(0, -4) + '.tsx');
+      }
+
       let targetFile: string | null = null;
       let targetExports: Map<string, ExportNode> | null = null;
 
-      for (const ext of extensions) {
-        const testPath = basePath + ext;
+      for (const testPath of candidates) {
         if (exportIndex.has(testPath)) {
           targetFile = testPath;
           targetExports = exportIndex.get(testPath)!;
           break;
         }
-        // Also check modulesByFile in case exports haven't been indexed yet
-        if (!targetFile && modulesByFile.has(testPath)) {
+        if (modulesByFile.has(testPath)) {
           targetFile = testPath;
           targetExports = exportIndex.get(testPath) || new Map();
           break;

package/src/storage/backends/RFDBServerBackend.ts

@@ -18,15 +18,14 @@
  *   await backend.flush();
  */
 
-import { RFDBClient } from '@grafema/rfdb-client';
-import { existsSync, unlinkSync } from 'fs';
-import { spawn, type ChildProcess } from 'child_process';
+import { RFDBClient, type BatchHandle } from '@grafema/rfdb-client';
+import type { ChildProcess } from 'child_process';
 import { join, dirname } from 'path';
-import { setTimeout as sleep } from 'timers/promises';
 
 import type { WireNode, WireEdge, FieldDeclaration, CommitDelta, AttrQuery as RFDBAttrQuery } from '@grafema/types';
 import type { NodeType, EdgeType } from '@grafema/types';
-import { findRfdbBinary } from '../../utils/findRfdbBinary.js';
+import { startRfdbServer } from '../../utils/startRfdbServer.js';
+import { GRAFEMA_VERSION, getSchemaVersion } from '../../version.js';
 import type { BaseNodeRecord, EdgeRecord, AnyBrandedNode } from '@grafema/types';
 import { brandNodeInternal } from '../../core/brandNodeInternal.js';
 import type { AttrQuery, GraphStats, GraphExport } from '../../core/GraphBackend.js';
@@ -201,66 +200,19 @@ export class RFDBServerBackend {
   }
 
   /**
-   * Find RFDB server binary using shared utility.
-   * Delegates to findRfdbBinary() for consistent search across all entry points.
-   */
-  private _findServerBinary(): string | null {
-    const binaryPath = findRfdbBinary();
-    if (binaryPath) {
-      this.log(`[RFDBServerBackend] Found binary: ${binaryPath}`);
-    }
-    return binaryPath;
-  }
-
-  /**
-   * Start RFDB server process
+   * Start RFDB server process using shared utility.
    */
   private async _startServer(): Promise<void> {
     if (!this.dbPath) {
       throw new Error('dbPath required to start RFDB server');
     }
 
-    // Find server binary - check multiple locations
-    const binaryPath = this._findServerBinary();
-    if (!binaryPath) {
-      throw new Error(
-        'RFDB server binary not found.\n' +
-        'Install @grafema/rfdb: npm install @grafema/rfdb\n' +
-        'Or build from source: cargo build --release --bin rfdb-server'
-      );
-    }
-
-    // Remove stale socket
-    if (existsSync(this.socketPath)) {
-      unlinkSync(this.socketPath);
-    }
-
-    this.log(`[RFDBServerBackend] Starting: ${binaryPath} ${this.dbPath} --socket ${this.socketPath}`);
-
-    this.serverProcess = spawn(binaryPath, [this.dbPath, '--socket', this.socketPath], {
-      stdio: ['ignore', 'ignore', 'inherit'], // stdin/stdout ignored, stderr inherited
-      detached: true, // Allow server to outlive this process
-    });
-
-    // Don't let server process prevent parent from exiting
-    this.serverProcess.unref();
-
-    this.serverProcess.on('error', (err: Error) => {
-      this.logError(`[RFDBServerBackend] Server process error:`, err);
+    await startRfdbServer({
+      dbPath: this.dbPath,
+      socketPath: this.socketPath,
+      waitTimeoutMs: 5000,
+      logger: this.silent ? undefined : { debug: (m: string) => this.log(m) },
     });
-
-    // Wait for socket to appear
-    let attempts = 0;
-    while (!existsSync(this.socketPath) && attempts < 50) {
-      await sleep(100);
-      attempts++;
-    }
-
-    if (!existsSync(this.socketPath)) {
-      throw new Error(`RFDB server failed to start (socket not created after ${attempts * 100}ms)`);
-    }
-
-    this.log(`[RFDBServerBackend] Server started on ${this.socketPath}`);
   }
 
   /**
@@ -274,9 +226,28 @@ export class RFDBServerBackend {
     try {
       const hello = await this.client.hello(3);
       this.protocolVersion = hello.protocolVersion;
+      this._checkServerVersion(hello.serverVersion);
     } catch {
       // Server predates hello command or doesn't support v3 — safe v2 fallback
       this.protocolVersion = 2;
+      this.log('[RFDBServerBackend] WARNING: Server does not support version negotiation. Consider updating rfdb-server.');
+    }
+  }
+
+  /**
+   * Validate server version against expected client version.
+   * Warns on mismatch but never fails — version differences are informational.
+   */
+  private _checkServerVersion(serverVersion: string): void {
+    if (!serverVersion) return;
+    const expected = getSchemaVersion(GRAFEMA_VERSION);
+    const actual = getSchemaVersion(serverVersion);
+    if (actual !== expected) {
+      this.log(
+        `[RFDBServerBackend] WARNING: rfdb-server version mismatch — ` +
+        `server v${serverVersion}, expected v${GRAFEMA_VERSION}. ` +
+        `Update with: grafema server restart`
+      );
     }
   }
 
@@ -769,10 +740,13 @@ export class RFDBServerBackend {
   /**
    * Commit the current batch to the server atomically.
    * Returns a CommitDelta describing what changed.
+   *
+   * @param tags - Optional tags for the commit
+   * @param deferIndex - When true, server writes data but skips index rebuild.
    */
-  async commitBatch(tags?: string[]): Promise<CommitDelta> {
+  async commitBatch(tags?: string[], deferIndex?: boolean, protectedTypes?: string[]): Promise<CommitDelta> {
     if (!this.client) throw new Error('Not connected to RFDB server');
-    return this.client.commitBatch(tags);
+    return this.client.commitBatch(tags, deferIndex, protectedTypes);
   }
 
   /**
@@ -822,6 +796,24 @@ export class RFDBServerBackend {
     this.client.abortBatch();
   }
 
+  /**
+   * Rebuild all secondary indexes after deferred-index commits (REG-487).
+   * Call this once after a series of commitBatch(tags, true) calls.
+   */
+  async rebuildIndexes(): Promise<void> {
+    if (!this.client) throw new Error('Not connected to RFDB server');
+    await this.client.rebuildIndexes();
+  }
+
+  /**
+   * Create an isolated batch handle for concurrent-safe batching (REG-487).
+   * Each handle has its own buffers — safe for parallel workers.
+   */
+  createBatch(): BatchHandle {
+    if (!this.client) throw new Error('Not connected to RFDB server');
+    return this.client.createBatch();
+  }
+
   // ===========================================================================
   // Export/Import
   // ===========================================================================