bug(agentdb): GNN integration affected by RuvectorLayer constructor panic

[ruvnet]

Issue Summary

Upstream Issue: ruvnet/RuVector#216
Related: #118

AgentDB's GNN capabilities are affected by the RuvectorLayer constructor panic issue in @ruvector/gnn.

Impact on AgentDB

AgentDB exports and uses GNN functionality through:

• packages/agentdb/src/services/GNNService.ts
• Graph neural network routing for semantic search
• Pattern matching and skill recommendations

Problem

When AgentDB tries to initialize GNN routing, the constructor receives invalid parameters:

```typescript
// AgentDB GNNService
import { RuvectorLayer } from '@ruvector/gnn';

class GNNService {
constructor(config: GNNConfig) {
// This panics if config.heads doesn't divide evenly into 128
this.layer = new RuvectorLayer(config.heads);
}
}
```

Root Causes

1. Parameter validation: No client-side validation before calling constructor
2. Panic propagation: Constructor panics are fatal across FFI (NAPI/WASM)
3. Default config: Default config may have invalid head counts

Affected Features

• ✅ Basic AgentDB: Still works (memory, embeddings, search)
• ❌ GNN Routing: Fails to initialize with invalid config
• ❌ Semantic Router: Depends on GNN, fails gracefully
• ❌ Pattern Matching: Fallback to basic similarity works

Temporary Fix (AgentDB Side)

```typescript
// Add validation in GNNService constructor
class GNNService {
constructor(config: GNNConfig) {
// Validate before calling native constructor
const EMBEDDING_DIM = 128;
if (EMBEDDING_DIM % config.heads !== 0) {
throw new Error(
`GNN head count must divide evenly into ${EMBEDDING_DIM}. + \Got ${config.heads}, valid options: [1, 2, 4, 8, 16, 32, 64, 128]`
);
}

this.layer = new RuvectorLayer(config.heads);

}
}
```

Long-term Fix (Upstream)

Waiting for @ruvector/gnn to return Result instead of panic:
```rust
pub fn new(num_heads: usize) -> Result<Self, GnnError> {
if EMBEDDING_DIM % num_heads != 0 {
return Err(GnnError::InvalidHeads {
num_heads,
embedding_dim: EMBEDDING_DIM
});
}
Ok(Self { num_heads, ... })
}
```

Action Items

• Add client-side validation in AgentDB GNNService
• Update default config to use valid head count (8)
• Add integration tests for invalid configs
• Update to @ruvector/gnn when Result-based API available
• Document valid head count options

Files to Update

1. `packages/agentdb/src/services/GNNService.ts` - Add validation
2. `packages/agentdb/src/index.ts` - Export validation helper
3. `packages/agentdb/tests/gnn-service.test.ts` - Test error handling

Default Config

```typescript
// Ensure default config uses valid head count
export const DEFAULT_GNN_CONFIG: GNNConfig = {
heads: 8, // VALID: 128 % 8 = 0 ✅
layers: 3,
hiddenDim: 256,
dropout: 0.1
};
```

Related

• Upstream: fix(ruvector-gnn): RuvectorLayer constructor panics instead of returning Result RuVector#216
• agentic-flow tracking: bug: GNNService incorrectly passes config.layers to RuvectorLayer constructor #118
• Package: `packages/agentdb` (3.0.0-alpha.9)
• Dependency: `@ruvector/gnn@0.1.24`

Priority

P2 - AgentDB core functionality works, GNN is enhancement. Workaround available.

Workaround for Users

```typescript
import { AgentDB } from 'agentdb';

// Use valid head count
const db = new AgentDB({
gnn: {
enabled: true,
heads: 8, // Must be 1, 2, 4, 8, 16, 32, 64, or 128
layers: 3
}
});
```