proffesor-for-testing__agentic-qe/docs/implementation/specs/SPEC-050-A-ml-observability-persistence.md

SPEC-050-A: ML Observability and Persistence

Field	Value
Specification ID	SPEC-050-A
Parent ADR	ADR-050
Version	1.0
Status	In Progress
Last Updated	2026-01-20
Author	GOAP Specialist

---

Overview

This specification covers Actions 1-4 from the GOAP plan: ML Observability Layer, Q-Learning Persistence, SONA Pattern Persistence, and Silent Fallback Removal.

---

Action 1: ML Observability Layer

Priority: P0 (Critical) Estimated Time: 4 hours

Interface Definition

// File: v3/src/integrations/ruvector/observability.ts
export interface MLObservabilityMetrics {
  mlUsed: number;
  fallbackUsed: number;
  mlLatencyMs: number[];
  fallbackReasons: Map<string, number>;
}

export interface MLObservabilityReport {
  mlUsageRate: number;           // mlUsed / (mlUsed + fallbackUsed)
  avgMlLatencyMs: number;
  topFallbackReasons: Array<{ reason: string; count: number }>;
  alertTriggered: boolean;
}

export class RuVectorObservability {
  private metrics: MLObservabilityMetrics;
  private alertThreshold = 0.2; // Alert if ML usage drops below 20%

  recordMLUsage(component: string, used: boolean, latencyMs?: number): void;
  recordFallback(component: string, reason: string): void;
  checkAndAlert(): void; // Emit alert if fallback rate too high
  getReport(): MLObservabilityReport;
}

Requirements

• RuVector wrappers exist (v3/src/integrations/ruvector/)
• Fallback implementations exist (fallback.ts)
• All ruvector calls emit metrics
• usedML flag on every routing result
• Alert system for fallback usage

---

Action 2: Q-Learning Persistence

Priority: P0 (Critical) Estimated Time: 8 hours

Implementation

// File: v3/src/integrations/ruvector/persistent-q-router.ts
export class PersistentQLearningRouter implements QLearningRouter {
  private store: QValueStore;
  private ewcConfig: EWCConfig;

  constructor(config: PersistentQLearningConfig) {
    this.store = createQValueStore();
    this.ewcConfig = {
      lambda: 1000.0,      // EWC regularization strength
      consolidationInterval: 3600000, // 1 hour
      fisherSampleSize: 100,
    };
  }

  async initialize(): Promise<void> {
    await this.store.initialize();
    await this.loadQValues(); // Restore from DB
  }

  async routeTask(task: TestTask): Promise<AgentRoutingResult> {
    const result = await this.mlRoute(task);
    await this.store.setQValue(agentId, stateKey, actionKey, qValue);
    return result;
  }

  private async consolidateWithEWC(): Promise<void> {
    // Apply EWC++ to prevent forgetting old patterns
  }
}

Requirements

• QValueStore exists with SQLite backend
• UnifiedPersistenceManager available
• Q-Learning router exists
• Q-values persist to memory.db
• Q-values restored on router initialization
• EWC++ prevents catastrophic forgetting

---

Action 3: SONA Pattern Persistence

Priority: P0 (Critical) Estimated Time: 6 hours

Implementation

// File: v3/src/integrations/ruvector/sona-persistence.ts
export class PersistentSONAEngine extends QESONA {
  private persistence: UnifiedPersistenceManager;

  async initialize(): Promise<void> {
    await super.initialize();
    await this.restorePatterns();
  }

  async storePattern(pattern: QESONAPattern): Promise<void> {
    super.storePattern(pattern);
    await this.persistPattern(pattern);
  }

  private async persistPattern(pattern: QESONAPattern): Promise<void> {
    const db = this.persistence.getDatabase();
    db.prepare(`
      INSERT INTO sona_patterns (id, type, domain, embedding, confidence, created_at)
      VALUES (?, ?, ?, ?, ?, datetime('now'))
    `).run(pattern.id, pattern.type, pattern.domain,
           JSON.stringify(pattern.stateEmbedding), pattern.confidence);
  }

  private async restorePatterns(): Promise<void> {
    const patterns = this.persistence.getDatabase().prepare(`
      SELECT * FROM sona_patterns ORDER BY confidence DESC LIMIT 10000
    `).all();
    for (const p of patterns) {
      super.importPatterns([this.deserializePattern(p)]);
    }
  }
}

Requirements

• QESONA wrapper exists
• UnifiedPersistenceManager available
• SONA patterns persist to memory.db
• Patterns restored on SONA initialization
• Cross-agent pattern sharing via DB

---

Action 4: Remove Silent Fallbacks

Priority: P1 (High) Estimated Time: 12 hours

Modified Provider

// File: v3/src/integrations/ruvector/provider.ts (modified)
export function createQLearningRouter(config?: QLearningConfig): QLearningRouter {
  const observability = getRuVectorObservability();

  // TRY ML FIRST - no preemptive fallback
  try {
    const router = new RuVectorQLearningRouter(config);
    await router.initialize(); // Will throw if ruvector unavailable
    observability.recordMLUsage('q-learning', true);
    return router;
  } catch (error) {
    // ONLY fall back on actual error
    observability.recordFallback('q-learning', error.message);
    observability.alert({
      component: 'q-learning',
      reason: error.message,
      recommendation: 'Install/fix ruvector to enable ML routing',
    });
    return new FallbackQLearningRouter(); // Still works, but user knows
  }
}

Files to Modify

• v3/src/integrations/ruvector/provider.ts
• All domain coordinators that create ruvector components

Requirements

• Fallbacks only used on explicit error
• All fallback usage logged and alerted
• No more silent degradation

---

Database Schema Additions

-- Migration: 20260120_add_sona_patterns.sql

CREATE TABLE IF NOT EXISTS sona_patterns (
  id TEXT PRIMARY KEY,
  type TEXT NOT NULL,
  domain TEXT NOT NULL,
  embedding TEXT NOT NULL,  -- JSON array
  confidence REAL DEFAULT 0.0,
  created_at TEXT DEFAULT (datetime('now')),
  updated_at TEXT DEFAULT (datetime('now'))
);

CREATE INDEX IF NOT EXISTS idx_sona_patterns_domain ON sona_patterns(domain);
CREATE INDEX IF NOT EXISTS idx_sona_patterns_confidence ON sona_patterns(confidence DESC);

---

Agent Assignments

Action	Agent	Phase
Action 1	qe-learning-coordinator	Phase 1
Action 2	qe-pattern-learner	Phase 1
Action 3	qe-pattern-learner	Phase 2
Action 4	qe-test-architect, qe-coverage-specialist	Phase 2

---

Changelog

Version	Date	Author	Changes
1.0	2026-01-20	GOAP Specialist	Initial specification