Merge pull request #266 from CambrianTech/feature/rust-module-consolidation

Rust Module Consolidation Phase 2: Optimization & Compute Migration

Author: joelteply

src/debug/jtag/browser/generated.ts

@@ -1,7 +1,7 @@
 /**
  * Browser Structure Registry - Auto-generated
  *
- * Contains 11 daemons and 187 commands and 2 adapters and 28 widgets.
+ * Contains 11 daemons and 188 commands and 2 adapters and 28 widgets.
  * Generated by scripts/generate-structure.ts - DO NOT EDIT MANUALLY
  */
 
@@ -152,6 +152,7 @@ import { PersonaLearningPatternQueryBrowserCommand } from './../commands/persona
 import { PingBrowserCommand } from './../commands/ping/browser/PingBrowserCommand';
 import { PositronCursorBrowserCommand } from './../commands/positron/cursor/browser/PositronCursorBrowserCommand';
 import { ProcessRegistryBrowserCommand } from './../commands/process-registry/browser/ProcessRegistryBrowserCommand';
+import { RuntimeMetricsBrowserCommand } from './../commands/runtime/metrics/browser/RuntimeMetricsBrowserCommand';
 import { SessionCreateBrowserCommand } from './../commands/session/create/browser/SessionCreateBrowserCommand';
 import { SessionDestroyBrowserCommand } from './../commands/session/destroy/browser/SessionDestroyBrowserCommand';
 import { SessionGetIdBrowserCommand } from './../commands/session/get-id/browser/SessionGetIdBrowserCommand';
@@ -974,6 +975,11 @@ export const BROWSER_COMMANDS: CommandEntry[] = [
     className: 'ProcessRegistryBrowserCommand',
     commandClass: ProcessRegistryBrowserCommand
   },
+{
+    name: 'runtime/metrics',
+    className: 'RuntimeMetricsBrowserCommand',
+    commandClass: RuntimeMetricsBrowserCommand
+  },
 {
     name: 'session/create',
     className: 'SessionCreateBrowserCommand',

src/debug/jtag/commands/ai/rag/query-open/server/RagQueryOpenServerCommand.ts

@@ -17,6 +17,7 @@ import { v4 as uuidv4 } from 'uuid';
 import type { CodeIndexEntity } from '../../../../../system/data/entities/CodeIndexEntity';
 import type { DataListParams, DataListResult } from '../../../../data/list/shared/DataListTypes';
 import type { BaseEntity } from '../../../../../system/data/entities/BaseEntity';
+import { RustCoreIPCClient } from '../../../../../workers/continuum-core/bindings/RustCoreIPC';
 
 import { EmbeddingGenerate } from '../../../embedding/generate/shared/EmbeddingGenerateTypes';
 import { DataList } from '../../../../data/list/shared/DataListTypes';
@@ -125,8 +126,9 @@ export class RagQueryOpenServerCommand extends RagQueryOpenCommand {
 
       console.log(`🔎 Fetched ${listResult.items.length} indexed entries`);
 
-      // Step 3: Calculate cosine similarity for each entry
-      const scoredResults: CodeSearchResult[] = [];
+      // Step 3: Filter entries and prepare for Rust similarity computation
+      const filteredEntries: CodeIndexEntity[] = [];
+      const targetEmbeddings: number[][] = [];
 
       for (const entry of listResult.items as readonly CodeIndexEntity[]) {
         // Skip entries without embeddings
@@ -142,21 +144,47 @@ export class RagQueryOpenServerCommand extends RagQueryOpenCommand {
           continue;
         }
 
-        // Calculate cosine similarity
-        const similarity = this.cosineSimilarity(queryEmbedding, entry.embedding);
+        filteredEntries.push(entry);
+        targetEmbeddings.push(entry.embedding);
+      }
 
-        // Only include results above relevance threshold
-        if (similarity >= minRelevance) {
-          scoredResults.push({
-            entry,
-            relevanceScore: similarity
-          });
+      // Step 4: Use Rust for parallel similarity computation (Rayon-accelerated)
+      let scoredResults: CodeSearchResult[] = [];
+
+      if (targetEmbeddings.length > 0) {
+        try {
+          const ipc = RustCoreIPCClient.getInstance();
+          const { results: topKResults, durationMs } = await ipc.embeddingTopK(
+            queryEmbedding,
+            targetEmbeddings,
+            targetEmbeddings.length, // Get all results, filter by threshold
+            minRelevance
+          );
+
+          console.log(`🦀 Rust computed ${topKResults.length} similarities in ${durationMs}ms`);
+
+          // Map indices back to entries
+          scoredResults = topKResults.map(r => ({
+            entry: filteredEntries[r.index],
+            relevanceScore: r.similarity
+          }));
+        } catch (error) {
+          // Fallback to TypeScript if Rust unavailable
+          console.log(`⚠️ Rust similarity unavailable, using TypeScript fallback: ${error}`);
+          for (let i = 0; i < filteredEntries.length; i++) {
+            const similarity = this.cosineSimilarity(queryEmbedding, targetEmbeddings[i]);
+            if (similarity >= minRelevance) {
+              scoredResults.push({
+                entry: filteredEntries[i],
+                relevanceScore: similarity
+              });
+            }
+          }
+          // Sort by relevance (highest first) - Rust already returns sorted
+          scoredResults.sort((a, b) => b.relevanceScore - a.relevanceScore);
         }
       }
 
-      // Step 4: Sort by relevance (highest first)
-      scoredResults.sort((a, b) => b.relevanceScore - a.relevanceScore);
-
       console.log(`🔎 Found ${scoredResults.length} matches above threshold ${minRelevance}`);
 
       // Step 5: Create query handle

src/debug/jtag/commands/runtime/metrics/.npmignore

@@ -0,0 +1,20 @@
+# Development files
+.eslintrc*
+tsconfig*.json
+vitest.config.ts
+
+# Build artifacts
+*.js.map
+*.d.ts.map
+
+# IDE
+.vscode/
+.idea/
+
+# Logs
+*.log
+npm-debug.log*
+
+# OS files
+.DS_Store
+Thumbs.db

src/debug/jtag/commands/runtime/metrics/README.md

@@ -0,0 +1,185 @@
+# Runtime Metrics Command
+
+Query Rust module performance metrics including latency percentiles, command counts, and slow command tracking. Enables AI-driven system analysis and optimization.
+
+## Table of Contents
+
+- [Usage](#usage)
+  - [CLI Usage](#cli-usage)
+  - [Tool Usage](#tool-usage)
+- [Parameters](#parameters)
+- [Result](#result)
+- [Examples](#examples)
+- [Testing](#testing)
+  - [Unit Tests](#unit-tests)
+  - [Integration Tests](#integration-tests)
+- [Getting Help](#getting-help)
+- [Access Level](#access-level)
+- [Implementation Notes](#implementation-notes)
+
+## Usage
+
+### CLI Usage
+
+From the command line using the jtag CLI:
+
+```bash
+./jtag runtime/metrics [options]
+```
+
+### Tool Usage
+
+From Persona tools or programmatic access using `Commands.execute()`:
+
+```typescript
+import { Commands } from '@system/core/shared/Commands';
+
+const result = await Commands.execute('runtime/metrics', {
+  // your parameters here
+});
+```
+
+## Parameters
+
+- **mode** (optional): `'all' | 'module' | 'slow' | 'list'` - Query mode: 'all' for all modules (default), 'module' for specific module, 'slow' for recent slow commands, 'list' for module configs
+- **module** (optional): `string` - Module name when mode='module' (e.g., 'data', 'embedding', 'cognition')
+
+## Result
+
+Returns `RuntimeMetricsResult` with:
+
+Returns CommandResult with:
+- **modules**: `ModuleMetrics[]` - Array of module metrics (when mode='all' or 'module')
+- **slowCommands**: `SlowCommand[]` - Array of slow commands (when mode='slow')
+- **moduleConfigs**: `ModuleConfig[]` - Array of module configurations (when mode='list')
+- **count**: `number` - Number of items in the result
+- **thresholdMs**: `number` - Slow command threshold in ms (when mode='slow')
+
+## Examples
+
+### Get metrics for all modules
+
+```bash
+./jtag runtime/metrics
+```
+
+**Expected result:**
+{ modules: [...], count: 13 }
+
+### Get metrics for a specific module
+
+```bash
+./jtag runtime/metrics --mode=module --module=embedding
+```
+
+**Expected result:**
+{ modules: [{ moduleName: 'embedding', avgTimeMs: 90, p99Ms: 552, ... }], count: 1 }
+
+### List recent slow commands
+
+```bash
+./jtag runtime/metrics --mode=slow
+```
+
+**Expected result:**
+{ slowCommands: [...], count: 5, thresholdMs: 50 }
+
+### List all module configurations
+
+```bash
+./jtag runtime/metrics --mode=list
+```
+
+**Expected result:**
+{ moduleConfigs: [...], count: 13 }
+
+## Getting Help
+
+### Using the Help Tool
+
+Get detailed usage information for this command:
+
+**CLI:**
+```bash
+./jtag help runtime/metrics
+```
+
+**Tool:**
+```typescript
+// Use your help tool with command name 'runtime/metrics'
+```
+
+### Using the README Tool
+
+Access this README programmatically:
+
+**CLI:**
+```bash
+./jtag readme runtime/metrics
+```
+
+**Tool:**
+```typescript
+// Use your readme tool with command name 'runtime/metrics'
+```
+
+## Testing
+
+### Unit Tests
+
+Test command logic in isolation using mock dependencies:
+
+```bash
+# Run unit tests (no server required)
+npx tsx commands/Runtime Metrics/test/unit/RuntimeMetricsCommand.test.ts
+```
+
+**What's tested:**
+- Command structure and parameter validation
+- Mock command execution patterns
+- Required parameter validation (throws ValidationError)
+- Optional parameter handling (sensible defaults)
+- Performance requirements
+- Assertion utility helpers
+
+**TDD Workflow:**
+1. Write/modify unit test first (test-driven development)
+2. Run test, see it fail
+3. Implement feature
+4. Run test, see it pass
+5. Refactor if needed
+
+### Integration Tests
+
+Test command with real client connections and system integration:
+
+```bash
+# Prerequisites: Server must be running
+npm start  # Wait 90+ seconds for deployment
+
+# Run integration tests
+npx tsx commands/Runtime Metrics/test/integration/RuntimeMetricsIntegration.test.ts
+```
+
+**What's tested:**
+- Client connection to live system
+- Real command execution via WebSocket
+- ValidationError handling for missing params
+- Optional parameter defaults
+- Performance under load
+- Various parameter combinations
+
+**Best Practice:**
+Run unit tests frequently during development (fast feedback). Run integration tests before committing (verify system integration).
+
+## Access Level
+
+**ai-safe** - Safe for AI personas to call autonomously
+
+## Implementation Notes
+
+- **Shared Logic**: Core business logic in `shared/RuntimeMetricsTypes.ts`
+- **Browser**: Browser-specific implementation in `browser/RuntimeMetricsBrowserCommand.ts`
+- **Server**: Server-specific implementation in `server/RuntimeMetricsServerCommand.ts`
+- **Unit Tests**: Isolated testing in `test/unit/RuntimeMetricsCommand.test.ts`
+- **Integration Tests**: System testing in `test/integration/RuntimeMetricsIntegration.test.ts`

src/debug/jtag/commands/runtime/metrics/browser/RuntimeMetricsBrowserCommand.ts

@@ -0,0 +1,21 @@
+/**
+ * Runtime Metrics Command - Browser Implementation
+ *
+ * Query Rust module performance metrics including latency percentiles, command counts, and slow command tracking. Enables AI-driven system analysis and optimization.
+ */
+
+import { CommandBase, type ICommandDaemon } from '@daemons/command-daemon/shared/CommandBase';
+import type { JTAGContext } from '@system/core/types/JTAGTypes';
+import type { RuntimeMetricsParams, RuntimeMetricsResult } from '../shared/RuntimeMetricsTypes';
+
+export class RuntimeMetricsBrowserCommand extends CommandBase<RuntimeMetricsParams, RuntimeMetricsResult> {
+
+  constructor(context: JTAGContext, subpath: string, commander: ICommandDaemon) {
+    super('runtime/metrics', context, subpath, commander);
+  }
+
+  async execute(params: RuntimeMetricsParams): Promise<RuntimeMetricsResult> {
+    console.log('🌐 BROWSER: Delegating Runtime Metrics to server');
+    return await this.remoteExecute(params);
+  }
+}

src/debug/jtag/commands/runtime/metrics/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@jtag-commands/runtime/metrics",
+  "version": "1.0.0",
+  "description": "Query Rust module performance metrics including latency percentiles, command counts, and slow command tracking. Enables AI-driven system analysis and optimization.",
+  "main": "server/RuntimeMetricsServerCommand.ts",
+  "types": "shared/RuntimeMetricsTypes.ts",
+  "scripts": {
+    "test": "npm run test:unit && npm run test:integration",
+    "test:unit": "npx vitest run test/unit/*.test.ts",
+    "test:integration": "npx tsx test/integration/RuntimeMetricsIntegration.test.ts",
+    "lint": "npx eslint **/*.ts",
+    "typecheck": "npx tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@jtag/core": "*"
+  },
+  "files": [
+    "shared/**/*.ts",
+    "browser/**/*.ts",
+    "server/**/*.ts",
+    "test/**/*.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "jtag",
+    "command",
+    "runtime/metrics"
+  ],
+  "license": "MIT",
+  "author": "",
+  "repository": {
+    "type": "git",
+    "url": ""
+  }
+}