agentic-qe 3.7.21 → 3.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (164) hide show
  1. package/.claude/helpers/brain-checkpoint.cjs +4 -1
  2. package/.claude/helpers/statusline-v3.cjs +3 -1
  3. package/.claude/skills/skills-manifest.json +1 -1
  4. package/CHANGELOG.md +45 -0
  5. package/README.md +2 -14
  6. package/assets/helpers/statusline-v3.cjs +3 -1
  7. package/dist/cli/brain-commands.js +6 -10
  8. package/dist/cli/bundle.js +7441 -4327
  9. package/dist/cli/commands/audit.d.ts +43 -0
  10. package/dist/cli/commands/audit.js +125 -0
  11. package/dist/cli/commands/hooks.js +29 -6
  12. package/dist/cli/commands/init.js +1 -73
  13. package/dist/cli/commands/learning.js +270 -13
  14. package/dist/cli/commands/ruvector-commands.d.ts +15 -0
  15. package/dist/cli/commands/ruvector-commands.js +271 -0
  16. package/dist/cli/handlers/init-handler.d.ts +0 -1
  17. package/dist/cli/handlers/init-handler.js +0 -6
  18. package/dist/cli/index.js +4 -2
  19. package/dist/context/sources/defect-source.js +2 -2
  20. package/dist/context/sources/memory-source.js +2 -2
  21. package/dist/context/sources/requirements-source.js +2 -2
  22. package/dist/coordination/behavior-tree/decorators.d.ts +108 -0
  23. package/dist/coordination/behavior-tree/decorators.js +251 -0
  24. package/dist/coordination/behavior-tree/index.d.ts +12 -0
  25. package/dist/coordination/behavior-tree/index.js +15 -0
  26. package/dist/coordination/behavior-tree/nodes.d.ts +165 -0
  27. package/dist/coordination/behavior-tree/nodes.js +338 -0
  28. package/dist/coordination/behavior-tree/qe-trees.d.ts +105 -0
  29. package/dist/coordination/behavior-tree/qe-trees.js +181 -0
  30. package/dist/coordination/coherence-action-gate.d.ts +284 -0
  31. package/dist/coordination/coherence-action-gate.js +512 -0
  32. package/dist/coordination/index.d.ts +4 -0
  33. package/dist/coordination/index.js +8 -0
  34. package/dist/coordination/reasoning-qec.d.ts +315 -0
  35. package/dist/coordination/reasoning-qec.js +585 -0
  36. package/dist/coordination/task-executor.d.ts +16 -0
  37. package/dist/coordination/task-executor.js +99 -0
  38. package/dist/coordination/workflow-orchestrator.d.ts +29 -0
  39. package/dist/coordination/workflow-orchestrator.js +42 -0
  40. package/dist/domains/visual-accessibility/cnn-visual-regression.d.ts +135 -0
  41. package/dist/domains/visual-accessibility/cnn-visual-regression.js +327 -0
  42. package/dist/domains/visual-accessibility/index.d.ts +1 -0
  43. package/dist/domains/visual-accessibility/index.js +4 -0
  44. package/dist/governance/coherence-validator.d.ts +112 -0
  45. package/dist/governance/coherence-validator.js +180 -0
  46. package/dist/governance/index.d.ts +1 -0
  47. package/dist/governance/index.js +2 -0
  48. package/dist/governance/witness-chain.d.ts +311 -0
  49. package/dist/governance/witness-chain.js +509 -0
  50. package/dist/init/index.d.ts +0 -2
  51. package/dist/init/index.js +0 -1
  52. package/dist/init/init-wizard-steps.d.ts +10 -0
  53. package/dist/init/init-wizard-steps.js +87 -1
  54. package/dist/init/init-wizard.d.ts +1 -9
  55. package/dist/init/init-wizard.js +3 -69
  56. package/dist/init/orchestrator.js +0 -1
  57. package/dist/init/phases/01-detection.js +0 -27
  58. package/dist/init/phases/07-hooks.js +6 -4
  59. package/dist/init/phases/phase-interface.d.ts +0 -1
  60. package/dist/init/settings-merge.js +1 -1
  61. package/dist/integrations/browser/qe-dashboard/clustering.d.ts +48 -0
  62. package/dist/integrations/browser/qe-dashboard/clustering.js +183 -0
  63. package/dist/integrations/browser/qe-dashboard/index.d.ts +12 -0
  64. package/dist/integrations/browser/qe-dashboard/index.js +15 -0
  65. package/dist/integrations/browser/qe-dashboard/pattern-explorer.d.ts +165 -0
  66. package/dist/integrations/browser/qe-dashboard/pattern-explorer.js +260 -0
  67. package/dist/integrations/browser/qe-dashboard/wasm-vector-store.d.ts +144 -0
  68. package/dist/integrations/browser/qe-dashboard/wasm-vector-store.js +277 -0
  69. package/dist/integrations/ruvector/cognitive-container-codec.d.ts +51 -0
  70. package/dist/integrations/ruvector/cognitive-container-codec.js +180 -0
  71. package/dist/integrations/ruvector/cognitive-container.d.ts +125 -0
  72. package/dist/integrations/ruvector/cognitive-container.js +306 -0
  73. package/dist/integrations/ruvector/coherence-gate.d.ts +309 -0
  74. package/dist/integrations/ruvector/coherence-gate.js +631 -0
  75. package/dist/integrations/ruvector/compressed-hnsw-integration.d.ts +176 -0
  76. package/dist/integrations/ruvector/compressed-hnsw-integration.js +301 -0
  77. package/dist/integrations/ruvector/dither-adapter.d.ts +122 -0
  78. package/dist/integrations/ruvector/dither-adapter.js +295 -0
  79. package/dist/integrations/ruvector/domain-transfer.d.ts +129 -0
  80. package/dist/integrations/ruvector/domain-transfer.js +220 -0
  81. package/dist/integrations/ruvector/feature-flags.d.ts +214 -2
  82. package/dist/integrations/ruvector/feature-flags.js +167 -2
  83. package/dist/integrations/ruvector/filter-adapter.d.ts +71 -0
  84. package/dist/integrations/ruvector/filter-adapter.js +285 -0
  85. package/dist/integrations/ruvector/gnn-wrapper.d.ts +20 -0
  86. package/dist/integrations/ruvector/gnn-wrapper.js +40 -0
  87. package/dist/integrations/ruvector/hnsw-health-monitor.d.ts +237 -0
  88. package/dist/integrations/ruvector/hnsw-health-monitor.js +394 -0
  89. package/dist/integrations/ruvector/index.d.ts +8 -2
  90. package/dist/integrations/ruvector/index.js +18 -2
  91. package/dist/integrations/ruvector/interfaces.d.ts +40 -0
  92. package/dist/integrations/ruvector/sona-persistence.d.ts +54 -0
  93. package/dist/integrations/ruvector/sona-persistence.js +162 -0
  94. package/dist/integrations/ruvector/sona-three-loop.d.ts +392 -0
  95. package/dist/integrations/ruvector/sona-three-loop.js +814 -0
  96. package/dist/integrations/ruvector/sona-wrapper.d.ts +97 -0
  97. package/dist/integrations/ruvector/sona-wrapper.js +147 -3
  98. package/dist/integrations/ruvector/spectral-math.d.ts +101 -0
  99. package/dist/integrations/ruvector/spectral-math.js +254 -0
  100. package/dist/integrations/ruvector/temporal-compression.d.ts +163 -0
  101. package/dist/integrations/ruvector/temporal-compression.js +318 -0
  102. package/dist/integrations/ruvector/thompson-sampler.d.ts +61 -0
  103. package/dist/integrations/ruvector/thompson-sampler.js +118 -0
  104. package/dist/integrations/ruvector/transfer-coherence-stub.d.ts +80 -0
  105. package/dist/integrations/ruvector/transfer-coherence-stub.js +63 -0
  106. package/dist/integrations/ruvector/transfer-verification.d.ts +119 -0
  107. package/dist/integrations/ruvector/transfer-verification.js +115 -0
  108. package/dist/kernel/hnsw-adapter.d.ts +52 -1
  109. package/dist/kernel/hnsw-adapter.js +139 -4
  110. package/dist/kernel/hnsw-index-provider.d.ts +5 -0
  111. package/dist/kernel/native-hnsw-backend.d.ts +110 -0
  112. package/dist/kernel/native-hnsw-backend.js +408 -0
  113. package/dist/kernel/unified-memory.js +5 -6
  114. package/dist/learning/aqe-learning-engine.d.ts +2 -0
  115. package/dist/learning/aqe-learning-engine.js +65 -0
  116. package/dist/learning/experience-capture-middleware.js +20 -0
  117. package/dist/learning/experience-capture.d.ts +10 -0
  118. package/dist/learning/experience-capture.js +34 -0
  119. package/dist/learning/index.d.ts +2 -2
  120. package/dist/learning/index.js +4 -4
  121. package/dist/learning/metrics-tracker.d.ts +11 -0
  122. package/dist/learning/metrics-tracker.js +29 -13
  123. package/dist/learning/pattern-lifecycle.d.ts +30 -1
  124. package/dist/learning/pattern-lifecycle.js +92 -20
  125. package/dist/learning/pattern-store.d.ts +8 -0
  126. package/dist/learning/pattern-store.js +8 -2
  127. package/dist/learning/qe-unified-memory.js +1 -28
  128. package/dist/learning/regret-tracker.d.ts +201 -0
  129. package/dist/learning/regret-tracker.js +361 -0
  130. package/dist/mcp/bundle.js +5915 -474
  131. package/dist/routing/index.d.ts +4 -2
  132. package/dist/routing/index.js +3 -1
  133. package/dist/routing/neural-tiny-dancer-router.d.ts +268 -0
  134. package/dist/routing/neural-tiny-dancer-router.js +514 -0
  135. package/dist/routing/queen-integration.js +5 -5
  136. package/dist/routing/routing-config.d.ts +6 -0
  137. package/dist/routing/routing-config.js +1 -0
  138. package/dist/routing/simple-neural-router.d.ts +76 -0
  139. package/dist/routing/simple-neural-router.js +202 -0
  140. package/dist/routing/tiny-dancer-router.d.ts +20 -1
  141. package/dist/routing/tiny-dancer-router.js +21 -2
  142. package/dist/test-scheduling/dag-attention-scheduler.d.ts +81 -0
  143. package/dist/test-scheduling/dag-attention-scheduler.js +358 -0
  144. package/dist/test-scheduling/dag-attention-types.d.ts +81 -0
  145. package/dist/test-scheduling/dag-attention-types.js +10 -0
  146. package/dist/test-scheduling/index.d.ts +1 -0
  147. package/dist/test-scheduling/index.js +4 -0
  148. package/dist/test-scheduling/pipeline.d.ts +8 -0
  149. package/dist/test-scheduling/pipeline.js +28 -0
  150. package/package.json +6 -2
  151. package/dist/cli/commands/migrate.d.ts +0 -9
  152. package/dist/cli/commands/migrate.js +0 -566
  153. package/dist/init/init-wizard-migration.d.ts +0 -52
  154. package/dist/init/init-wizard-migration.js +0 -345
  155. package/dist/init/migration/config-migrator.d.ts +0 -31
  156. package/dist/init/migration/config-migrator.js +0 -149
  157. package/dist/init/migration/data-migrator.d.ts +0 -72
  158. package/dist/init/migration/data-migrator.js +0 -232
  159. package/dist/init/migration/detector.d.ts +0 -44
  160. package/dist/init/migration/detector.js +0 -105
  161. package/dist/init/migration/index.d.ts +0 -8
  162. package/dist/init/migration/index.js +0 -8
  163. package/dist/learning/v2-to-v3-migration.d.ts +0 -86
  164. package/dist/learning/v2-to-v3-migration.js +0 -529
@@ -63,6 +63,25 @@ export const SONA_PATTERNS_SCHEMA = `
63
63
  CREATE INDEX IF NOT EXISTS idx_sona_patterns_confidence ON sona_patterns(confidence DESC);
64
64
  CREATE INDEX IF NOT EXISTS idx_sona_patterns_updated ON sona_patterns(updated_at DESC);
65
65
  `;
66
+ /**
67
+ * SONA Fisher matrices table schema - stores EWC++ state per domain
68
+ */
69
+ export const SONA_FISHER_SCHEMA = `
70
+ -- SONA Fisher Information Matrices (Task 2.2: EWC++ Persistence)
71
+ CREATE TABLE IF NOT EXISTS sona_fisher_matrices (
72
+ domain TEXT PRIMARY KEY,
73
+ fisher_diagonal BLOB NOT NULL,
74
+ optimal_params BLOB NOT NULL,
75
+ base_weights BLOB,
76
+ dimension INTEGER NOT NULL,
77
+ task_boundaries INTEGER NOT NULL DEFAULT 0,
78
+ consolidation_cycles INTEGER NOT NULL DEFAULT 0,
79
+ request_count INTEGER NOT NULL DEFAULT 0,
80
+ ewc_lambda REAL NOT NULL DEFAULT 1000.0,
81
+ created_at TEXT DEFAULT (datetime('now')),
82
+ updated_at TEXT DEFAULT (datetime('now'))
83
+ );
84
+ `;
66
85
  /**
67
86
  * Default persistent SONA configuration
68
87
  */
@@ -140,6 +159,36 @@ export class PersistentSONAEngine {
140
159
  if (this.config.loadOnInit) {
141
160
  await this.loadPatterns();
142
161
  }
162
+ // Wire three-loop engine with Fisher persistence when feature flag is on
163
+ const { isSONAThreeLoopEnabled } = await import('./feature-flags.js');
164
+ if (isSONAThreeLoopEnabled()) {
165
+ this.baseEngine.initThreeLoopEngine();
166
+ // Wire Fisher persistence: consolidation auto-saves to SQLite
167
+ this.baseEngine.setFisherPersistence((domain, fisher, optimal, base, meta) => {
168
+ this.saveFisherMatrix(domain, fisher, optimal, base, meta);
169
+ }, this.config.domain);
170
+ // Restore Fisher state from SQLite if available
171
+ const saved = this.loadFisherMatrix(this.config.domain);
172
+ if (saved) {
173
+ const engine = this.baseEngine.getThreeLoopEngine();
174
+ if (engine) {
175
+ engine.restoreFisher({
176
+ fisherDiagonal: saved.fisherDiagonal,
177
+ optimalParams: saved.optimalParams,
178
+ baseWeights: saved.baseWeights,
179
+ requestCount: saved.requestCount,
180
+ });
181
+ logger.info('Three-loop engine restored Fisher state from SQLite', {
182
+ domain: this.config.domain,
183
+ requestCount: saved.requestCount,
184
+ taskBoundaries: saved.taskBoundaries,
185
+ });
186
+ }
187
+ }
188
+ logger.info('Three-loop engine initialized with Fisher persistence', {
189
+ domain: this.config.domain,
190
+ });
191
+ }
143
192
  this.initialized = true;
144
193
  console.log(`[PersistentSONAEngine] Initialized: domain=${this.config.domain}`);
145
194
  }
@@ -160,6 +209,12 @@ export class PersistentSONAEngine {
160
209
  console.log('[PersistentSONAEngine] Creating sona_patterns table');
161
210
  this.db.exec(SONA_PATTERNS_SCHEMA);
162
211
  }
212
+ // Check if Fisher matrices table exists
213
+ const fisherTableExists = this.db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='sona_fisher_matrices'`).get();
214
+ if (!fisherTableExists) {
215
+ console.log('[PersistentSONAEngine] Creating sona_fisher_matrices table');
216
+ this.db.exec(SONA_FISHER_SCHEMA);
217
+ }
163
218
  }
164
219
  /**
165
220
  * Prepare commonly used statements
@@ -245,6 +300,26 @@ export class PersistentSONAEngine {
245
300
  DELETE FROM sona_patterns
246
301
  WHERE updated_at < datetime('now', '-' || ? || ' days')
247
302
  `));
303
+ // Fisher matrix statements (Task 2.2: EWC++ Persistence)
304
+ this.prepared.set('upsertFisher', this.db.prepare(`
305
+ INSERT INTO sona_fisher_matrices (
306
+ domain, fisher_diagonal, optimal_params, base_weights,
307
+ dimension, task_boundaries, consolidation_cycles,
308
+ request_count, ewc_lambda, created_at, updated_at
309
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))
310
+ ON CONFLICT(domain) DO UPDATE SET
311
+ fisher_diagonal = excluded.fisher_diagonal,
312
+ optimal_params = excluded.optimal_params,
313
+ base_weights = excluded.base_weights,
314
+ dimension = excluded.dimension,
315
+ task_boundaries = excluded.task_boundaries,
316
+ consolidation_cycles = excluded.consolidation_cycles,
317
+ request_count = excluded.request_count,
318
+ ewc_lambda = excluded.ewc_lambda,
319
+ updated_at = datetime('now')
320
+ `));
321
+ this.prepared.set('getFisher', this.db.prepare(`SELECT * FROM sona_fisher_matrices WHERE domain = ?`));
322
+ this.prepared.set('deleteFisher', this.db.prepare(`DELETE FROM sona_fisher_matrices WHERE domain = ?`));
248
323
  }
249
324
  /**
250
325
  * Load patterns from SQLite into base engine
@@ -644,6 +719,72 @@ export class PersistentSONAEngine {
644
719
  console.log(`[PersistentSONAEngine] Closed: domain=${this.config.domain}`);
645
720
  }
646
721
  // ==========================================================================
722
+ // Fisher Matrix Persistence (Task 2.2: EWC++)
723
+ // ==========================================================================
724
+ /**
725
+ * Save Fisher Information Matrix and optimal parameters to SQLite.
726
+ *
727
+ * Persists the EWC++ state for a domain so it survives across sessions.
728
+ * This includes the Fisher diagonal, optimal parameters, base weights,
729
+ * and metadata about task boundaries and consolidation cycles.
730
+ *
731
+ * @param domain - Domain identifier for the Fisher state
732
+ * @param fisherDiagonal - Fisher Information Matrix diagonal
733
+ * @param optimalParams - Optimal parameters at last task boundary
734
+ * @param baseWeights - Current base weights (optional)
735
+ * @param metadata - Additional metadata (task boundaries, cycles, etc.)
736
+ */
737
+ saveFisherMatrix(domain, fisherDiagonal, optimalParams, baseWeights, metadata) {
738
+ this.ensureInitialized();
739
+ const stmt = this.prepared.get('upsertFisher');
740
+ if (!stmt)
741
+ throw new Error('Fisher upsert statement not prepared');
742
+ const fisherBuf = this.float32ToBuffer(fisherDiagonal);
743
+ const optimalBuf = this.float32ToBuffer(optimalParams);
744
+ const baseBuf = baseWeights ? this.float32ToBuffer(baseWeights) : null;
745
+ stmt.run(domain, fisherBuf, optimalBuf, baseBuf, fisherDiagonal.length, metadata?.taskBoundaries ?? 0, metadata?.consolidationCycles ?? 0, metadata?.requestCount ?? 0, metadata?.ewcLambda ?? 1000.0);
746
+ logger.info('Fisher matrix saved', { domain, dimension: fisherDiagonal.length });
747
+ }
748
+ /**
749
+ * Load Fisher Information Matrix and optimal parameters from SQLite.
750
+ *
751
+ * @param domain - Domain identifier to load Fisher state for
752
+ * @returns Fisher state or null if not found
753
+ */
754
+ loadFisherMatrix(domain) {
755
+ this.ensureInitialized();
756
+ const stmt = this.prepared.get('getFisher');
757
+ if (!stmt)
758
+ throw new Error('Fisher get statement not prepared');
759
+ const row = stmt.get(domain);
760
+ if (!row)
761
+ return null;
762
+ return {
763
+ fisherDiagonal: this.bufferToFloat32(row.fisher_diagonal),
764
+ optimalParams: this.bufferToFloat32(row.optimal_params),
765
+ baseWeights: row.base_weights ? this.bufferToFloat32(row.base_weights) : null,
766
+ dimension: row.dimension,
767
+ taskBoundaries: row.task_boundaries,
768
+ consolidationCycles: row.consolidation_cycles,
769
+ requestCount: row.request_count,
770
+ ewcLambda: row.ewc_lambda,
771
+ };
772
+ }
773
+ /**
774
+ * Delete Fisher matrix for a domain.
775
+ *
776
+ * @param domain - Domain identifier
777
+ * @returns true if a row was deleted
778
+ */
779
+ deleteFisherMatrix(domain) {
780
+ this.ensureInitialized();
781
+ const stmt = this.prepared.get('deleteFisher');
782
+ if (!stmt)
783
+ throw new Error('Fisher delete statement not prepared');
784
+ const result = stmt.run(domain);
785
+ return result.changes > 0;
786
+ }
787
+ // ==========================================================================
647
788
  // Server Integration
648
789
  // ==========================================================================
649
790
  /**
@@ -849,6 +990,27 @@ export class PersistentSONAEngine {
849
990
  }
850
991
  return arr;
851
992
  }
993
+ /**
994
+ * Convert Float32Array to Buffer (for Fisher matrix persistence)
995
+ */
996
+ float32ToBuffer(arr) {
997
+ const buffer = Buffer.alloc(arr.length * 4);
998
+ for (let i = 0; i < arr.length; i++) {
999
+ buffer.writeFloatLE(arr[i], i * 4);
1000
+ }
1001
+ return buffer;
1002
+ }
1003
+ /**
1004
+ * Convert Buffer to Float32Array (for Fisher matrix loading)
1005
+ */
1006
+ bufferToFloat32(buffer) {
1007
+ const count = buffer.length / 4;
1008
+ const arr = new Float32Array(count);
1009
+ for (let i = 0; i < count; i++) {
1010
+ arr[i] = buffer.readFloatLE(i * 4);
1011
+ }
1012
+ return arr;
1013
+ }
852
1014
  }
853
1015
  // ============================================================================
854
1016
  // Factory Functions
@@ -0,0 +1,392 @@
1
+ /**
2
+ * SONA Three-Loop Coordination Engine
3
+ *
4
+ * Implements the three-loop architecture for continuous neural adaptation:
5
+ *
6
+ * 1. **Instant Loop** - Per-request MicroLoRA adaptation (<100us)
7
+ * Applies rank-1 weight updates for real-time personalization.
8
+ *
9
+ * 2. **Background Loop** - Periodic consolidation (every N requests)
10
+ * Merges instant adaptations into base model, runs EWC++ to prevent
11
+ * catastrophic forgetting, and updates the Fisher Information Matrix.
12
+ *
13
+ * 3. **Coordination Loop** - Cross-agent state synchronization
14
+ * Shares learned patterns across agent instances and manages
15
+ * domain-specific adaptation state.
16
+ *
17
+ * @module integrations/ruvector/sona-three-loop
18
+ */
19
+ /**
20
+ * Minimal interface for @ruvector/sona SonaEngine (NAPI).
21
+ * Used for optional delegation when the native engine is injected.
22
+ */
23
+ interface INativeSonaEngine {
24
+ applyMicroLora(features: number[]): number[];
25
+ forceLearn(): string;
26
+ tick(): string | null;
27
+ beginTrajectory(stateEmbedding: number[]): number;
28
+ addTrajectoryStep(trajectoryId: number, actionEmbedding: number[], attentionWeights: number[], reward: number): void;
29
+ endTrajectory(trajectoryId: number, quality: number): void;
30
+ }
31
+ /** Reset WASM loader state (for testing) */
32
+ export declare function resetWasmLoraLoader(): void;
33
+ /** Result from an instant MicroLoRA adaptation */
34
+ export interface AdaptationResult {
35
+ /** Adapted output weights */
36
+ adaptedWeights: Float32Array;
37
+ /** Time taken in microseconds */
38
+ latencyUs: number;
39
+ /** Whether the adaptation was applied (vs skipped) */
40
+ applied: boolean;
41
+ /** Adaptation magnitude (L2 norm of delta) */
42
+ magnitude: number;
43
+ /** Request counter at time of adaptation */
44
+ requestIndex: number;
45
+ }
46
+ /** Result from a background consolidation cycle */
47
+ export interface ConsolidationResult {
48
+ /** Whether consolidation was performed */
49
+ consolidated: boolean;
50
+ /** Number of instant adaptations merged */
51
+ adaptationsMerged: number;
52
+ /** EWC++ regularization loss before consolidation */
53
+ ewcLossBefore: number;
54
+ /** EWC++ regularization loss after consolidation */
55
+ ewcLossAfter: number;
56
+ /** Whether a new task boundary was detected */
57
+ taskBoundaryDetected: boolean;
58
+ /** Duration of consolidation in milliseconds */
59
+ durationMs: number;
60
+ }
61
+ /** Peer state for cross-agent synchronization */
62
+ export interface PeerState {
63
+ /** Unique peer identifier */
64
+ peerId: string;
65
+ /** Domain the peer operates in */
66
+ domain: string;
67
+ /** Peer's current adaptation vector */
68
+ adaptationVector: Float32Array;
69
+ /** Peer's Fisher diagonal (importance weights) */
70
+ fisherDiagonal: Float32Array;
71
+ /** Number of requests processed by peer */
72
+ requestCount: number;
73
+ /** Timestamp of last update */
74
+ lastUpdateMs: number;
75
+ }
76
+ /** EWC++ metrics for monitoring */
77
+ export interface EWCMetrics {
78
+ /** Current EWC++ regularization loss */
79
+ regularizationLoss: number;
80
+ /** Number of task boundaries detected */
81
+ taskBoundariesDetected: number;
82
+ /** Fisher Information Matrix trace (sum of diagonal) */
83
+ fisherTrace: number;
84
+ /** Average Fisher diagonal value */
85
+ avgFisherImportance: number;
86
+ /** Maximum Fisher diagonal value */
87
+ maxFisherImportance: number;
88
+ /** Number of parameters protected above threshold */
89
+ protectedParams: number;
90
+ /** Total consolidation cycles completed */
91
+ consolidationCycles: number;
92
+ /** EWC lambda (regularization strength) */
93
+ lambda: number;
94
+ }
95
+ /** Configuration for the three-loop engine */
96
+ export interface ThreeLoopConfig {
97
+ /** Dimension of the adaptation/weight space */
98
+ dimension: number;
99
+ /** MicroLoRA learning rate for instant adaptations */
100
+ microLoraLr: number;
101
+ /** Number of requests between background consolidation cycles */
102
+ consolidationInterval: number;
103
+ /** EWC++ regularization strength (lambda) */
104
+ ewcLambda: number;
105
+ /** Z-score threshold for task boundary detection */
106
+ taskBoundaryZScoreThreshold: number;
107
+ /** Decay factor for blending old/new Fisher estimates */
108
+ fisherDecay: number;
109
+ /** Number of gradient samples for Fisher estimation */
110
+ fisherSampleSize: number;
111
+ /** Importance threshold below which params are not protected */
112
+ importanceThreshold: number;
113
+ }
114
+ /** Default three-loop configuration */
115
+ export declare const DEFAULT_THREE_LOOP_CONFIG: ThreeLoopConfig;
116
+ /**
117
+ * Micro-Linear Adaptation (element-wise) for per-request weight updates.
118
+ *
119
+ * Applies W' = W + alpha * features element-wise.
120
+ * Not a true rank-1 outer product LoRA — for that, use native @ruvector/sona.
121
+ *
122
+ * This is intentionally lightweight for real-time use (<100us).
123
+ */
124
+ export declare class MicroLoRA {
125
+ /** Current rank-1 adaptation delta accumulated across requests */
126
+ adaptationVector: Float32Array;
127
+ /** Base weights (updated by background consolidation) */
128
+ baseWeights: Float32Array;
129
+ /** Learning rate for instant adaptation */
130
+ private readonly lr;
131
+ /** Count of adaptations applied since last consolidation */
132
+ private adaptationCount;
133
+ constructor(dimension: number, lr?: number);
134
+ /**
135
+ * Apply rank-1 instant adaptation to produce adapted weights.
136
+ *
137
+ * @param features - Input features for the current request
138
+ * @returns Adapted weights = baseWeights + adaptationVector + lr * features
139
+ */
140
+ adapt(features: number[]): Float32Array;
141
+ /**
142
+ * Merge accumulated adaptations into base weights and reset delta.
143
+ * Called by the background loop during consolidation.
144
+ *
145
+ * @returns Number of adaptations that were merged
146
+ */
147
+ consolidate(): number;
148
+ /** Get the number of adaptations since last consolidation */
149
+ getAdaptationCount(): number;
150
+ /** Get the current effective weights (base + delta) */
151
+ getEffectiveWeights(): Float32Array;
152
+ /** Get the L2 norm of the adaptation delta */
153
+ getAdaptationMagnitude(): number;
154
+ /** Reset adaptation state without affecting base weights */
155
+ resetAdaptation(): void;
156
+ }
157
+ /**
158
+ * EWC++ for preventing catastrophic forgetting across task boundaries.
159
+ *
160
+ * Maintains a diagonal Fisher Information Matrix that captures parameter
161
+ * importance. When a new task boundary is detected (via gradient z-score),
162
+ * the Fisher matrix is updated using online blending:
163
+ * F_new = decay * F_old + (1 - decay) * F_current
164
+ *
165
+ * The EWC loss penalizes deviation from optimal parameters:
166
+ * L_EWC = (lambda/2) * sum(F_i * (theta_i - theta*_i)^2)
167
+ */
168
+ export declare class EWCPlusPlus {
169
+ /** Diagonal Fisher Information Matrix (importance weights) */
170
+ fisherMatrix: Float32Array;
171
+ /** Optimal parameters at last task boundary */
172
+ optimalParams: Float32Array;
173
+ /** Regularization strength */
174
+ private readonly lambda;
175
+ /** Decay for blending old/new Fisher estimates */
176
+ private readonly fisherDecay;
177
+ /** Z-score threshold for task boundary detection */
178
+ private readonly zScoreThreshold;
179
+ /** Importance threshold for parameter protection */
180
+ private readonly importanceThreshold;
181
+ /** Running statistics for gradient magnitudes */
182
+ private gradientHistory;
183
+ private gradientMean;
184
+ private gradientVariance;
185
+ /** Number of task boundaries detected */
186
+ private taskBoundaryCount;
187
+ /** Number of consolidation cycles */
188
+ private consolidationCount;
189
+ constructor(dimension: number, lambda?: number, fisherDecay?: number, zScoreThreshold?: number, importanceThreshold?: number);
190
+ /**
191
+ * Detect whether a task boundary has occurred based on the z-score
192
+ * of the gradient magnitude change.
193
+ *
194
+ * A sudden spike in gradient magnitude signals a distribution shift,
195
+ * indicating we have moved to a new task.
196
+ *
197
+ * @param gradients - Current gradient vector
198
+ * @returns true if a task boundary is detected
199
+ */
200
+ detectTaskBoundary(gradients: Float32Array): boolean;
201
+ /**
202
+ * Compute EWC++ regularization loss for current parameters.
203
+ *
204
+ * L_EWC = (lambda/2) * sum(F_i * (theta_i - theta*_i)^2)
205
+ *
206
+ * @param currentParams - Current model parameters
207
+ * @returns Scalar regularization loss
208
+ */
209
+ computeLoss(currentParams: Float32Array): number;
210
+ /**
211
+ * Update the Fisher Information Matrix using online EWC++ blending.
212
+ *
213
+ * F_new = decay * F_old + (1 - decay) * F_sample
214
+ *
215
+ * The sample Fisher is approximated from squared gradients.
216
+ *
217
+ * Gradient samples should be outcome-weighted (REINFORCE-style), not raw
218
+ * request features. Call recordOutcome() to generate proper gradient proxies.
219
+ *
220
+ * @param gradientSamples - Array of gradient vectors to estimate Fisher
221
+ * @param currentParams - Current parameters to snapshot as optimal
222
+ */
223
+ updateFisher(gradientSamples: Float32Array[], currentParams: Float32Array): void;
224
+ /** Get metrics for monitoring */
225
+ getMetrics(): EWCMetrics;
226
+ /** Get the number of task boundaries detected */
227
+ getTaskBoundaryCount(): number;
228
+ /** Get the Fisher diagonal as a copy */
229
+ getFisherDiagonal(): Float32Array;
230
+ /** Get the optimal parameters as a copy */
231
+ getOptimalParams(): Float32Array;
232
+ /** Load Fisher matrix from persisted data */
233
+ loadFisher(fisher: Float32Array, optimal: Float32Array): void;
234
+ /** Update running gradient statistics (Welford's algorithm) */
235
+ private updateGradientStats;
236
+ }
237
+ /**
238
+ * Three-loop coordination engine for SONA neural adaptation.
239
+ *
240
+ * Combines MicroLoRA instant adaptation, EWC++ background consolidation,
241
+ * and cross-agent coordination into a unified engine.
242
+ */
243
+ export declare class SONAThreeLoopEngine {
244
+ private readonly config;
245
+ private readonly microLora;
246
+ private readonly ewc;
247
+ private readonly nativeEngine;
248
+ private wasmLora;
249
+ private requestCount;
250
+ private lastConsolidationRequest;
251
+ private peerStates;
252
+ private gradientBuffer;
253
+ private lastFeatures;
254
+ constructor(config?: Partial<ThreeLoopConfig>, nativeEngine?: INativeSonaEngine | null);
255
+ /**
256
+ * Perform instant per-request MicroLoRA adaptation.
257
+ *
258
+ * This is the hot path and must complete in <100us.
259
+ * When a native @ruvector/sona engine is available, delegates to the
260
+ * Rust implementation for true rank-1 LoRA. Otherwise falls back to
261
+ * the TypeScript element-wise approximation.
262
+ *
263
+ * @param requestFeatures - Feature vector for the current request
264
+ * @returns Adaptation result with adapted weights and timing
265
+ */
266
+ instantAdapt(requestFeatures: number[]): AdaptationResult;
267
+ /**
268
+ * Record the outcome of a request for REINFORCE-style gradient estimation.
269
+ * Must be called after instantAdapt() with the reward signal.
270
+ *
271
+ * Computes gradient proxy: reward * last_features (REINFORCE estimator)
272
+ * This is what gets buffered for Fisher estimation, NOT raw features.
273
+ *
274
+ * @param reward - Scalar reward (e.g., 1.0 for success, -1.0 for failure, 0.0 for neutral)
275
+ * @param requestIndex - The requestIndex from the AdaptationResult (for matching)
276
+ */
277
+ recordOutcome(reward: number, requestIndex?: number): void;
278
+ /**
279
+ * Run background consolidation cycle.
280
+ *
281
+ * This merges accumulated MicroLoRA adaptations into base weights,
282
+ * checks for task boundaries, and runs EWC++ if a boundary is detected.
283
+ * When a native @ruvector/sona engine is available, also triggers
284
+ * native background learning via forceLearn() and tick().
285
+ * Should be called periodically (every N requests via shouldConsolidate()).
286
+ *
287
+ * @returns Consolidation result with metrics
288
+ */
289
+ backgroundConsolidate(): ConsolidationResult;
290
+ /**
291
+ * Check if background consolidation is due.
292
+ */
293
+ shouldConsolidate(): boolean;
294
+ /**
295
+ * Synchronize state with peer agents.
296
+ *
297
+ * Merges peer adaptation vectors using Fisher-weighted averaging:
298
+ * For each parameter, the peer with higher Fisher importance has
299
+ * more influence on the merged value.
300
+ *
301
+ * @param peerStates - Array of peer states to synchronize with
302
+ */
303
+ syncWithPeers(peerStates: PeerState[]): void;
304
+ /**
305
+ * Get our current state for sharing with peers.
306
+ */
307
+ getLocalPeerState(peerId: string, domain: string): PeerState;
308
+ /**
309
+ * Get EWC++ metrics for monitoring and diagnostics.
310
+ */
311
+ getEWCMetrics(): EWCMetrics;
312
+ /**
313
+ * Get the Fisher diagonal for persistence.
314
+ */
315
+ getFisherDiagonal(): Float32Array;
316
+ /**
317
+ * Get the optimal parameters for persistence.
318
+ */
319
+ getOptimalParams(): Float32Array;
320
+ /**
321
+ * Load persisted Fisher matrix and optimal parameters.
322
+ */
323
+ loadFisher(fisher: Float32Array, optimalParams: Float32Array): void;
324
+ /**
325
+ * Get the current base weights from MicroLoRA.
326
+ */
327
+ getBaseWeights(): Float32Array;
328
+ /**
329
+ * Set base weights (e.g., from persistence).
330
+ */
331
+ setBaseWeights(weights: Float32Array): void;
332
+ /**
333
+ * Get the effective weights (base + adaptation delta).
334
+ */
335
+ getEffectiveWeights(): Float32Array;
336
+ /** Get the total number of requests processed */
337
+ getRequestCount(): number;
338
+ /** Get the engine configuration */
339
+ getConfig(): ThreeLoopConfig;
340
+ /** Get the connected peer states */
341
+ getPeerStates(): Map<string, PeerState>;
342
+ /** Get direct access to internal MicroLoRA (for testing) */
343
+ getMicroLoRA(): MicroLoRA;
344
+ /** Get direct access to internal EWC++ (for testing) */
345
+ getEWC(): EWCPlusPlus;
346
+ /**
347
+ * Apply EWC++ regularization to pull weights toward optimal.
348
+ *
349
+ * For parameters with high Fisher importance, nudge the current
350
+ * weights back toward the optimal values to prevent forgetting.
351
+ */
352
+ private applyEWCRegularization;
353
+ /**
354
+ * Persist Fisher matrix, optimal parameters, and base weights to SQLite
355
+ * via PersistentSONAEngine.saveFisherMatrix().
356
+ *
357
+ * Call this after backgroundConsolidate() to ensure EWC++ state survives
358
+ * across sessions. Typically called at session end or after N consolidations.
359
+ *
360
+ * @param persistFn - Callback that receives data and writes to SQLite.
361
+ * Typically `(domain, fisher, optimal, base, meta) => persistentEngine.saveFisherMatrix(...)`.
362
+ * @param domain - Domain identifier for the Fisher state
363
+ */
364
+ persistFisher(persistFn: (domain: string, fisherDiagonal: Float32Array, optimalParams: Float32Array, baseWeights: Float32Array, metadata: {
365
+ taskBoundaries: number;
366
+ consolidationCycles: number;
367
+ requestCount: number;
368
+ ewcLambda: number;
369
+ }) => void, domain: string): void;
370
+ /**
371
+ * Restore Fisher matrix, optimal parameters, and base weights from SQLite.
372
+ *
373
+ * Call this on engine startup to restore EWC++ state from a previous session.
374
+ *
375
+ * @param data - Persisted data from PersistentSONAEngine.loadFisherMatrix()
376
+ */
377
+ restoreFisher(data: {
378
+ fisherDiagonal: Float32Array;
379
+ optimalParams: Float32Array;
380
+ baseWeights: Float32Array | null;
381
+ requestCount: number;
382
+ }): void;
383
+ }
384
+ /**
385
+ * Create a SONA Three-Loop Engine with the given configuration.
386
+ *
387
+ * @param config - Optional three-loop configuration overrides
388
+ * @param nativeEngine - Optional @ruvector/sona SonaEngine for native delegation
389
+ */
390
+ export declare function createSONAThreeLoopEngine(config?: Partial<ThreeLoopConfig>, nativeEngine?: INativeSonaEngine | null): SONAThreeLoopEngine;
391
+ export {};
392
+ //# sourceMappingURL=sona-three-loop.d.ts.map