fix: SonaTrajectoryService does not use native @ruvector/sona API correctly

[Andycodeman]

Bug Summary

SonaTrajectoryService (from the agentdb package) fails to properly integrate with the native @ruvector/sona engine, resulting in SONA trajectory learning being effectively disabled. The service stores the module object instead of instantiating a SonaEngine, and calls nonexistent methods (recordStep, record, addStep, predict, selectAction) instead of the actual native API.

This bug has existed since the file first appeared in agentdb@3.0.0-alpha.4 and is present in every version through alpha.10.

Source File Missing from Git

The SonaTrajectoryService TypeScript source file does not exist anywhere in the git source of ruvnet/agentic-flow (agentdb's repo) — not on main, not on any of the 18 feature branches, and not in the commit history. The file only exists in the npm-published dist/ directory.

This is part of a broader pattern: 4 service files and 5 controller files exist in the npm package but have no corresponding source in git.

Impact

• SONA native learning is completely non-functional — trajectories are never recorded in the native engine
• Pattern extraction fails — findPatterns is never called
• The service silently falls back to a simple JavaScript frequency counter, giving the appearance of working while providing no actual RL-based learning
• All Micro-LoRA, EWC++, and pattern clustering features of @ruvector/sona are bypassed
• The service reports engineType: 'native' and available: true while doing nothing with the native engine

Root Cause (3 bugs)

Bug 1: initialize() — Module vs Instance

Looks for SONA/Sona class name instead of SonaEngine. Falls back to storing the raw module object.

Bug 2: recordTrajectory() — Nonexistent Methods

Calls recordStep(), record(), addStep() — none exist on SonaEngine. Silent catch {}.

Bug 3: predict() — Nonexistent Methods

Calls predict(), selectAction() — neither exist. Falls back to frequency counter.

Fix

PR submitted: ruvnet/agentic-flow#121

• Uses SonaEngine.withConfig() for proper instantiation
• Uses beginTrajectory → addTrajectoryStep → endTrajectory → tick() pipeline
• Uses findPatterns() for pattern-based predictions
• 54/54 test assertions passing across 10 test categories
• Full backward compatibility maintained

[ruvnet]

Addressed in v3.5.22

The SONA trajectory service has been reworked in PR #1365:

• LocalSonaCoordinator now implements addTrajectoryStep(), endTrajectory(verdict, bank), and distillLearning(bank)
• Exported endTrajectoryWithVerdict() and distillLearning() functions for external use
• Auto-calls endTrajectory + distillLearning when step type is 'result'
• EWC++ consolidation is wired with updateFisherFromConfidences() and computeConfidencePenalty()
• @ruvector/learning-wasm@0.1.29 integrated with JS fallback classes (JsMicroLoRA, JsScopedLoRA, JsTrajectoryBuffer)

The trajectory service now follows the 4-step pipeline: RETRIEVE → JUDGE → DISTILL → CONSOLIDATE.

[ruvnet]

SONA trajectory service reworked in v3.5.22 with proper 4-step pipeline.

[Andycodeman]

Still broken in ruflo@3.5.28 / agentdb SonaTrajectoryService

The LocalSonaCoordinator added in PR #1365 (v3.5.22) correctly uses the @ruvector/sona API — but it only covers the MCP tool path (ruvector__hooks_trajectory_begin/step/end). The agentdb SonaTrajectoryService.js was never updated and all three original bugs remain.

Also note: PR ruvnet/agentic-flow#121 (the fix for SonaTrajectoryService.js itself) is still open/unmerged.

Reproduction (ruflo@3.5.28, @ruvector/sona@0.1.5)

npm install ruflo@latest
node -e "
const { SonaTrajectoryService } = require('./node_modules/agentdb/dist/src/services/SonaTrajectoryService.js');
(async () => {
  const svc = new SonaTrajectoryService();
  await svc.initialize();
  console.log('engineType:', svc.engineType);       // 'native' (WRONG — not a real engine)
  console.log('available:', svc.available);           // true (WRONG)
  console.log('sona constructor:', svc.sona?.constructor?.name); // 'Object' (raw module, not SonaEngine)
  console.log('has beginTrajectory?', typeof svc.sona?.beginTrajectory); // undefined
  console.log('has addTrajectoryStep?', typeof svc.sona?.addTrajectoryStep); // undefined
})();
"

Output:

[SonaTrajectoryService] Using native @ruvector/sona
engineType: native
available: true
sona constructor: Object
has beginTrajectory? undefined
has addTrajectoryStep? undefined

Bug 1 — initialize() stores the module object, not an engine instance

initialize() looks for mod.SONA or mod.Sona — neither exists. The actual export is mod.SonaEngine (class with static withConfig()). Falls through to typeof SONA === 'object' and stores the raw { SonaEngine: [Function] } module object as this.sona. Reports engineType: 'native' and available: true while holding a useless reference.

Bug 2 — recordTrajectory() calls nonexistent methods

Tries this.sona.recordStep(), this.sona.record(), this.sona.addStep() — all undefined. Silent catch {} swallows the failure, falls through to in-memory-only storage.

Correct API: SonaEngine.withConfig({...}) → beginTrajectory() → addTrajectoryStep() → endTrajectory() → tick()

Bug 3 — predict() calls nonexistent methods

Tries this.sona.predict(), this.sona.selectAction() — both undefined. Falls to frequencyPredict() (simple JS counter).

Correct API: SonaEngine.findPatterns()

Actual @ruvector/sona@0.1.5 API

SonaEngine static methods: withConfig
SonaEngine instance methods: addTrajectoryContext, addTrajectoryStep, applyBaseLora,
  applyMicroLora, beginTrajectory, endTrajectory, findPatterns, flush, forceLearn,
  getStats, isEnabled, setEnabled, setTrajectoryRoute, tick

What the v3.5.22 fix covers vs. what's still broken

Code path	Uses correct API?	Status
LocalSonaCoordinator (intelligence.js)	✅ beginTrajectory/addTrajectoryStep/endTrajectory/distillLearning	Fixed in PR #1365
MCP tools (ruvector__hooks_trajectory_*)	✅ Calls LocalSonaCoordinator	Works
agentdb SonaTrajectoryService.js	❌ recordStep/predict/selectAction (don't exist)	Still broken
hook-handler.cjs lifecycle (session start/end, post-edit)	❌ Zero SONA wiring	No integration

The SonaTrajectoryService.js file is identical in both agentdb and the agentic-flow bundle within @claude-flow/cli. The fix in agentic-flow PR #121 addresses this but was never merged.

[Andycodeman]

SONA Read Path Never Wired — Patterns Stored But Never Retrieved

Following up on my previous comment showing SonaTrajectoryService.js is still broken in agentdb. After deeper investigation, the issue goes beyond the broken service — the entire read path was never connected.

What We Found

Three systems run side-by-side in the hook pipeline, none sharing data:

System	Reads From	Writes To	Used During Prompts?
intelligence.cjs	.claude-flow/data/auto-memory-store.json (flat JSON)	ranked-context.json	Yes — getContext() on every prompt
learning-service.mjs	.claude-flow/learning/patterns.db (SQLite + HNSW)	Same SQLite DB	No — searchPatterns() exists but nothing calls it
V3 intelligence.js (LocalSonaCoordinator + LocalReasoningBank)	.claude-flow/neural/patterns.json	Same JSON file	No — only used via MCP tool path

Result: SONA patterns are written to SQLite/HNSW on every edit and task, but intelligence.cjs (the thing that actually runs per-prompt) only reads from JSON files. The learning loop is open — patterns go in but never come back out.

Bug 1: Per-Edit Storage Is Noise

The post-edit SONA patch stores 'Edit ' + filename on every single file edit:

// hook-handler.cjs post-edit (SONA patch)
if (editFile) sonaBridge.storePattern('Edit ' + editFile.split('/').slice(-2).join('/'), 'edit');

This produces entries like "Edit src/main.ts" stored 27 times. The learning-service.mjs dedup catches exact matches and increments usage_count, but the content is just a filename — no semantic value. These are edit frequency counters, not learning patterns.

Ruflo's upstream intent (in intelligence.cjs consolidate()): track edits in pending-insights.jsonl, only promote to a pattern when a file crosses 3+ edits threshold, with context like "File X was edited N times — likely a hot path."

Bug 2: Per-Task Storage Produces Empty Patterns

The post-task SONA patch stores hookInput.taskDescription || hookInput.description || ...:

sonaBridge.storePattern(sonaPrompt.substring(0, 500), 'task');

But these fields are consistently empty in practice — zero task-domain patterns were ever stored across multiple projects we tested with active sessions.

Ruflo's upstream intent: post-task calls intelligence.feedback(true) which boosts confidence on previously matched patterns. It does NOT store new patterns.

Bug 3: Read Path Not Connected

intelligence.cjs getContext() — the function that runs on every prompt and produces the [INTELLIGENCE] Relevant patterns output — reads only from ranked-context.json (pre-computed from auto-memory-store.json). It never queries learning-service.mjs searchPatterns() or the SQLite/HNSW index.

The learning-service.mjs has a fully functional searchPatterns() method with HNSW cosine similarity search, but no code path ever calls it during prompt routing.

Bug 4: JSON.parse Failure on learning-service.mjs Output

learning-service.mjs prints log lines to stdout before JSON output:

[Embedding] agentic-flow not found, using fallback hash embeddings
[Learning] Initialized session session_1773956036350
[Learning] Short-term patterns: 26
[Learning] Long-term patterns: 0
{"patterns": [...]}

Any caller doing JSON.parse(stdout) fails silently because of the [Embedding]/[Learning] prefix lines.

What We Patched (working implementation)

1. Removed per-edit and per-task SONA storage. These now match upstream: post-edit logs to pending-insights.jsonl only; post-task calls intelligence.feedback(true) only.

2. Added consolidateEdits() to session-end. At session end, reads pending-insights.jsonl, finds files edited 3+ times, stores them as meaningful SONA patterns:

// sona-bridge.cjs consolidateEdits()
const strategy = `Hot path: ${shortFile} edited ${count}x this session`;
callLearningService('store', [strategy, 'edit-pattern']);

3. Wired the read path in intelligence.cjs init(). During session-restore, queries SONA HNSW with learning-service.mjs search and merges results into auto-memory-store.json as first-class entries. These get PageRank scores and are found by getContext() trigram matching with zero per-prompt overhead:

// intelligence.cjs init()
var sonaPatterns = sonaSearch('development patterns architecture bugs', 20);
// ... merge into store, rebuild graph

4. Fixed JSON.parse for learning-service.mjs stdout. Extracts JSON starting from first { character to skip log line prefix.

Pipeline After Patches

Hook	Action	Storage
post-edit	intelligence.recordEdit(file) → appends to jsonl	JSON log only
post-task	intelligence.feedback(true) → boosts confidence	Updates existing
session-end	consolidateEdits() → promotes 3+ edit files to SONA	SQLite/HNSW
session-restore	sonaSearch() → merges HNSW patterns into store → builds PageRank graph	SQLite read → JSON merge

Affected Files

• patch-sona.sh — Part 1 (hook-handler): removed per-edit/per-task stores, kept session-end consolidation. Part 4 (new): patches intelligence.cjs read path.
• sona-bridge.cjs — Added consolidateEdits() with 3+ edit threshold matching upstream intent.
• intelligence.cjs — Added sonaSearch() + HNSW merge at init, JSON.parse fix for log-prefixed output.

[Andycodeman]

Clarification: Bugs 1, 2, and 4 above were introduced by our own patch-sona.sh — not upstream ruflo. We've corrected those in our latest patch revision.

The core upstream issue remains Bug 3: the read/write pipeline for SQLite/HNSW is never connected. learning-service.mjs has a working searchPatterns() with HNSW cosine similarity, but nothing in the hook lifecycle ever calls it during prompt routing. intelligence.cjs getContext() only reads from flat JSON. Our updated patch closes this loop — SONA patterns stored in SQLite are now merged into the intelligence graph at session-restore and surfaced in [INTELLIGENCE] context on subsequent prompts.