agentic-qe 3.8.14 → 3.9.1

package/dist/integrations/ruvector/index.d.ts

@@ -86,7 +86,7 @@ export declare function getRuVectorStatus(config?: Partial<RuVectorConfig>): Pro
 }>;
 export * from './wrappers';
 export { RuVectorServiceProvider, getDomainRuVectorServices, getRuVectorProvider, getRuVectorServiceAvailability, type RuVectorServiceConfig, } from './provider';
-export { getRuVectorFeatureFlags, setRuVectorFeatureFlags, resetRuVectorFeatureFlags, isSONAEnabled, isFlashAttentionEnabled, isGNNIndexEnabled, isTemporalCompressionEnabled, isCrossDomainTransferEnabled, shouldLogMigrationMetrics, initFeatureFlagsFromEnv, isHDCFingerprintingEnabled, isCusumDriftDetectionEnabled, isDeltaEventSourcingEnabled, isEwcPlusPlusEnabled, isGraphMAEEnabled, isHopfieldMemoryEnabled, isColdTierGNNEnabled, isMetaLearningEnabled, isSublinearSolverEnabled, isSpectralSparsificationEnabled, isReservoirReplayEnabled, isEpropOnlineLearningEnabled, isGrangerCausalityEnabled, DEFAULT_FEATURE_FLAGS, type RuVectorFeatureFlags, } from './feature-flags';
+export { getRuVectorFeatureFlags, setRuVectorFeatureFlags, resetRuVectorFeatureFlags, isSONAEnabled, isFlashAttentionEnabled, isGNNIndexEnabled, isTemporalCompressionEnabled, isCrossDomainTransferEnabled, shouldLogMigrationMetrics, initFeatureFlagsFromEnv, isHDCFingerprintingEnabled, isCusumDriftDetectionEnabled, isDeltaEventSourcingEnabled, isEwcPlusPlusEnabled, isGraphMAEEnabled, isHopfieldMemoryEnabled, isColdTierGNNEnabled, isMetaLearningEnabled, isSublinearSolverEnabled, isSpectralSparsificationEnabled, isReservoirReplayEnabled, isEpropOnlineLearningEnabled, isGrangerCausalityEnabled, isCognitiveRoutingEnabled, isHyperbolicHnswEnabled, DEFAULT_FEATURE_FLAGS, type RuVectorFeatureFlags, } from './feature-flags';
 export { DomainTransferEngine, ThompsonSampler, createDomainTransferEngine, DEFAULT_DOMAIN_TRANSFER_CONFIG, DecayingBeta, PlateauDetector, ParetoFront, CuriosityBonus, type TransferCandidate, type TransferResult, type TransferRecord, type DomainTransferConfig, type ParetoPoint, } from './domain-transfer';
 export { TransferCoherenceStub, createTransferCoherenceGate, type ITransferCoherenceGate, type CoherenceValidation, } from './transfer-coherence-stub';
 export { TransferVerifier, createTransferVerifier, DEFAULT_VERIFICATION_CONFIG, type DomainPerformanceSnapshot, type TransferResultForVerification, type VerificationResult, type TransferVerificationConfig, } from './transfer-verification';
@@ -101,9 +101,10 @@ export { RvfDualWriter, createDualWriter } from './rvf-dual-writer.js';
 export type { DualWriteConfig, DualWriteResult, DivergenceReport } from './rvf-dual-writer.js';
 export { getSharedRvfDualWriter, getSharedRvfDualWriterSync, resetSharedRvfDualWriter, } from './shared-rvf-dual-writer.js';
 export { CognitiveContainer, createCognitiveContainer, generateSigningKeyPair, type ContainerSegment, type ContainerManifest, type ExportOptions, type ImportOptions, type ImportResult, type VerificationResult as CognitiveContainerVerificationResult, type ContainerInfo, type Ed25519KeyPair, } from './cognitive-container';
-export { HdcFingerprinter, createHdcFingerprinter, type HdcConfig, type PatternFingerprint, } from './hdc-fingerprint';
+export { HdcFingerprinter, createHdcFingerprinter, HDCPatternFingerprinter, createHDCFingerprinter, createRandomHypervector, bind, bundle, hammingDistance, hammingSimilarity, permute, type HdcConfig, type PatternFingerprint, } from './hdc-fingerprint';
 export { CusumDetector, type CusumConfig, type CusumResult, type GateType, } from './cusum-detector';
 export { DeltaTracker, PATTERN_DELTAS_SCHEMA, type DeltaEvent, type DeltaTrackerConfig, type JsonPatch, } from './delta-tracker';
+export { VectorDeltaTracker, createVectorDeltaTracker, type PatternDelta, type SparseChange, type DeltaSnapshot, type VectorDeltaTrackerConfig, type VectorDeltaTrackerStats, } from './vector-delta-tracker';
 export { GraphMAEEncoder, createGraphMAEEncoder, type GraphMAEConfig, type QEGraph, type GraphMAEResult, } from './graphmae-encoder';
 export { HopfieldMemory, createHopfieldMemory, type HopfieldConfig, type StoredPattern, type RecallResult, } from './hopfield-memory';
 export { ColdTierTrainer, InMemoryGraph, FileBackedGraph, createColdTierTrainer, type ColdTierConfig, type ColdTierGraph, type TrainingResult, type CacheStats, } from './cold-tier-trainer';
@@ -112,5 +113,7 @@ export { SpectralSparsifier, createSpectralSparsifier, type SparsifierGraph, typ
 export { ReservoirReplayBuffer, createReservoirReplayBuffer, type ReservoirEntry, type ReservoirConfig, type ReservoirStats, type CoherenceTier, } from './reservoir-replay';
 export { EpropNetwork, createEpropNetwork, type EpropConfig, type EpropStats, } from './eprop-learner';
 export { GrangerAnalyzer, createGrangerAnalyzer, type TestExecutionHistory, type CausalLink, type GrangerConfig, } from './temporal-causality';
+export { CognitiveRouter, MessagePredictor, OscillatoryRouter, createCognitiveRouter, type CognitiveRoutingConfig, type RoutedMessage, type RoutingStats, } from './cognitive-routing';
+export { HyperbolicHNSW, PoincareOperations, createHyperbolicHNSW, type HyperbolicConfig, type HyperbolicPoint, type HyperbolicSearchResult, } from './hyperbolic-hnsw';
 export { initializeSharedMemory, getSharedServerClient as getFleetSharedClient, setSharedServerClient, isSharedMemoryAvailable, getSharedMemoryStatus, getLastInitResult, shutdownSharedMemory, resetSharedMemoryState, integrateWithFleet, DEFAULT_SHARED_MEMORY_CONFIG, type SharedMemoryConfig, type SharedMemoryResult, type SharedMemoryStatus, } from './shared-memory';
 //# sourceMappingURL=index.d.ts.map

package/dist/integrations/ruvector/index.js

@@ -295,7 +295,9 @@ isGraphMAEEnabled, isHopfieldMemoryEnabled, isColdTierGNNEnabled,
 // Phase 5 Milestone 3 (ADR-087)
 isMetaLearningEnabled, isSublinearSolverEnabled, isSpectralSparsificationEnabled, isReservoirReplayEnabled, 
 // Phase 5 Milestone 4 (ADR-087)
-isEpropOnlineLearningEnabled, isGrangerCausalityEnabled, DEFAULT_FEATURE_FLAGS, } from './feature-flags';
+isEpropOnlineLearningEnabled, isGrangerCausalityEnabled, 
+// Phase 5 Milestone 5 (ADR-087)
+isCognitiveRoutingEnabled, isHyperbolicHnswEnabled, DEFAULT_FEATURE_FLAGS, } from './feature-flags';
 // ============================================================================
 // Cross-Domain Transfer Learning (ADR-084, Task 2.3)
 // ============================================================================
@@ -338,11 +340,13 @@ export { CognitiveContainer, createCognitiveContainer, generateSigningKeyPair, }
 // Phase 5: Pattern Intelligence (ADR-087, Milestone 1)
 // ============================================================================
 // R1: HDC Pattern Fingerprinting
-export { HdcFingerprinter, createHdcFingerprinter, } from './hdc-fingerprint';
+export { HdcFingerprinter, createHdcFingerprinter, HDCPatternFingerprinter, createHDCFingerprinter, createRandomHypervector, bind, bundle, hammingDistance, hammingSimilarity, permute, } from './hdc-fingerprint';
 // R2: CUSUM Drift Detection
 export { CusumDetector, } from './cusum-detector';
 // R3: Delta Event Sourcing
 export { DeltaTracker, PATTERN_DELTAS_SCHEMA, } from './delta-tracker';
+// R3: Sparse Vector Delta Event Sourcing (ADR-087 Milestone 1)
+export { VectorDeltaTracker, createVectorDeltaTracker, } from './vector-delta-tracker';
 // ============================================================================
 // Phase 5: Graph Learning (ADR-087, Milestone 2)
 // ============================================================================
@@ -369,6 +373,13 @@ export { EpropNetwork, createEpropNetwork, } from './eprop-learner';
 // R12: Granger Causality for Test Failure Prediction
 export { GrangerAnalyzer, createGrangerAnalyzer, } from './temporal-causality';
 // ============================================================================
+// Phase 5: Routing & Geometry (ADR-087, Milestone 5)
+// ============================================================================
+// R13: Cognitive Routing
+export { CognitiveRouter, MessagePredictor, OscillatoryRouter, createCognitiveRouter, } from './cognitive-routing';
+// R14: Hyperbolic HNSW
+export { HyperbolicHNSW, PoincareOperations, createHyperbolicHNSW, } from './hyperbolic-hnsw';
+// ============================================================================
 // Shared Memory Integration (Fleet Integration)
 // ============================================================================
 export { initializeSharedMemory, getSharedServerClient as getFleetSharedClient, setSharedServerClient, isSharedMemoryAvailable, getSharedMemoryStatus, getLastInitResult, shutdownSharedMemory, resetSharedMemoryState, integrateWithFleet, DEFAULT_SHARED_MEMORY_CONFIG, } from './shared-memory';

package/dist/integrations/ruvector/shared-rvf-adapter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared RVF Adapter Singleton
+ *
+ * Provides a single RvfNativeAdapter instance for .agentic-qe/patterns.rvf.
+ * Used by both the kernel (agent branching) and DreamEngine (COW dreams)
+ * to avoid dual file handles to the same .rvf file.
+ *
+ * Returns null when native bindings are unavailable — callers degrade
+ * gracefully.
+ *
+ * @module integrations/ruvector/shared-rvf-adapter
+ */
+import type { RvfNativeAdapter } from './rvf-native-adapter.js';
+/**
+ * Get or create the shared RvfNativeAdapter singleton for patterns.rvf.
+ *
+ * @param dataDir - Data directory (default: .agentic-qe)
+ * @param dimensions - Vector dimensions (default: 384)
+ * @returns The shared adapter, or null if native bindings are unavailable
+ */
+export declare function getSharedRvfAdapter(dataDir?: string, dimensions?: number): RvfNativeAdapter | null;
+/** Close the shared adapter and reset the singleton. */
+export declare function resetSharedRvfAdapter(): void;
+//# sourceMappingURL=shared-rvf-adapter.d.ts.map

package/dist/integrations/ruvector/shared-rvf-adapter.js

@@ -0,0 +1,55 @@
+/**
+ * Shared RVF Adapter Singleton
+ *
+ * Provides a single RvfNativeAdapter instance for .agentic-qe/patterns.rvf.
+ * Used by both the kernel (agent branching) and DreamEngine (COW dreams)
+ * to avoid dual file handles to the same .rvf file.
+ *
+ * Returns null when native bindings are unavailable — callers degrade
+ * gracefully.
+ *
+ * @module integrations/ruvector/shared-rvf-adapter
+ */
+let sharedAdapter = null;
+let initAttempted = false;
+/**
+ * Get or create the shared RvfNativeAdapter singleton for patterns.rvf.
+ *
+ * @param dataDir - Data directory (default: .agentic-qe)
+ * @param dimensions - Vector dimensions (default: 384)
+ * @returns The shared adapter, or null if native bindings are unavailable
+ */
+export function getSharedRvfAdapter(dataDir = '.agentic-qe', dimensions = 384) {
+    if (initAttempted)
+        return sharedAdapter;
+    initAttempted = true;
+    try {
+        // Dynamic require to match the bundled build pattern used elsewhere
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { isRvfNativeAvailable, createRvfStore } = require('./rvf-native-adapter.js');
+        if (!isRvfNativeAvailable()) {
+            console.warn('[RVF] Native bindings unavailable — agent branching and dream COW disabled. ' +
+                'Install @ruvector/rvf-node to enable.');
+            return null;
+        }
+        const path = require('path');
+        sharedAdapter = createRvfStore(path.join(dataDir, 'patterns.rvf'), dimensions);
+        return sharedAdapter;
+    }
+    catch (error) {
+        console.warn('[RVF] Shared adapter init failed:', error instanceof Error ? error.message : error);
+        return null;
+    }
+}
+/** Close the shared adapter and reset the singleton. */
+export function resetSharedRvfAdapter() {
+    if (sharedAdapter) {
+        try {
+            sharedAdapter.close();
+        }
+        catch { /* best effort */ }
+        sharedAdapter = null;
+    }
+    initAttempted = false;
+}
+//# sourceMappingURL=shared-rvf-adapter.js.map

package/dist/integrations/ruvector/shared-rvf-dual-writer.d.ts

@@ -12,6 +12,7 @@
  * continue with SQLite-only operation.
  */
 import type { RvfDualWriter } from './rvf-dual-writer.js';
+import type { RvfMigrationAdapter } from '../../persistence/rvf-migration-adapter.js';
 /**
  * Get or create the shared RvfDualWriter singleton.
  *
@@ -31,6 +32,11 @@ export declare function getSharedRvfDualWriter(): Promise<RvfDualWriter | null>;
  * initialized or if native RVF is unavailable.
  */
 export declare function getSharedRvfDualWriterSync(): RvfDualWriter | null;
+/**
+ * Get the shared RvfMigrationAdapter (ADR-072).
+ * Returns null if migration stage < 2 or if initialization has not completed.
+ */
+export declare function getSharedMigrationAdapter(): RvfMigrationAdapter | null;
 /**
  * Reset the shared RvfDualWriter singleton.
  *

package/dist/integrations/ruvector/shared-rvf-dual-writer.js

@@ -15,6 +15,7 @@
 // Singleton State
 // ============================================================================
 let sharedDualWriter = null;
+let sharedMigrationAdapter = null;
 let initPromise = null;
 /** Tracks whether we already attempted init (to avoid retrying on null result) */
 let initAttempted = false;
@@ -70,6 +71,35 @@ export async function getSharedRvfDualWriter() {
             });
             await writer.initialize();
             sharedDualWriter = writer;
+            // ADR-072: Initialize migration adapter when stage >= 2
+            try {
+                const { getRvfMigrationStage } = await import('./feature-flags.js');
+                const stage = getRvfMigrationStage();
+                if (stage >= 2) {
+                    const { RvfMigrationAdapter } = await import('../../persistence/rvf-migration-adapter.js');
+                    const migrationAdapter = new RvfMigrationAdapter({ stage });
+                    migrationAdapter.setSqliteDb(db);
+                    // Wire the RVF store from the dual-writer's native adapter
+                    const { getSharedRvfAdapter } = await import('./shared-rvf-adapter.js');
+                    const rvfAdapter = getSharedRvfAdapter();
+                    if (rvfAdapter) {
+                        // Wrap the native adapter as an RvfStore
+                        const rvfStore = {
+                            ingest: (entries) => rvfAdapter.ingest(entries),
+                            search: (query, k) => rvfAdapter.search(query, k).map(r => ({ id: r.id, score: r.score })),
+                            delete: (ids) => rvfAdapter.delete(ids),
+                            status: () => rvfAdapter.status(),
+                            close: () => { },
+                        };
+                        migrationAdapter.setRvfStore(rvfStore);
+                    }
+                    sharedMigrationAdapter = migrationAdapter;
+                    console.log(`[RVF] Migration adapter active at stage ${stage} (${['sqlite-only', 'hybrid', 'dual-sqlite', 'dual-rvf', 'rvf-primary'][stage]})`);
+                }
+            }
+            catch {
+                // Migration adapter is optional — dual-writer works without it
+            }
             return writer;
         }
         catch (error) {
@@ -100,6 +130,13 @@ export async function getSharedRvfDualWriter() {
 export function getSharedRvfDualWriterSync() {
     return sharedDualWriter;
 }
+/**
+ * Get the shared RvfMigrationAdapter (ADR-072).
+ * Returns null if migration stage < 2 or if initialization has not completed.
+ */
+export function getSharedMigrationAdapter() {
+    return sharedMigrationAdapter;
+}
 /**
  * Reset the shared RvfDualWriter singleton.
  *
@@ -116,6 +153,7 @@ export function resetSharedRvfDualWriter() {
         }
         sharedDualWriter = null;
     }
+    sharedMigrationAdapter = null;
     initPromise = null;
     initAttempted = false;
 }

package/dist/integrations/ruvector/sona-persistence.d.ts

@@ -213,6 +213,14 @@ export declare class PersistentSONAEngine {
      * @returns Consolidation result, or null if three-loop engine not initialized
      */
     backgroundConsolidate(): import('./sona-three-loop.js').ConsolidationResult | null;
+    /**
+     * Check if background consolidation is due (every N requests).
+     *
+     * Delegates to the base engine's shouldConsolidate().
+     *
+     * @returns true if consolidation interval has been reached
+     */
+    shouldConsolidate(): boolean;
     /**
      * Check if the three-loop engine is initialized and active.
      */

package/dist/integrations/ruvector/sona-persistence.js

@@ -594,6 +594,16 @@ export class PersistentSONAEngine {
         this.ensureInitialized();
         return this.baseEngine.backgroundConsolidate();
     }
+    /**
+     * Check if background consolidation is due (every N requests).
+     *
+     * Delegates to the base engine's shouldConsolidate().
+     *
+     * @returns true if consolidation interval has been reached
+     */
+    shouldConsolidate() {
+        return this.baseEngine.shouldConsolidate();
+    }
     /**
      * Check if the three-loop engine is initialized and active.
      */

package/dist/integrations/ruvector/vector-delta-tracker.d.ts

@@ -0,0 +1,96 @@
+/**
+ * R3: Sparse Vector Delta Event Sourcing (ADR-087, Milestone 1)
+ *
+ * Tracks pattern embedding version history using sparse delta encoding.
+ * Only changed dimensions are stored, giving massive compression for
+ * typical pattern updates where few dimensions change.
+ *
+ * Storage: In-memory (Map-based). SQLite integration deferred to later task.
+ *
+ * @module integrations/ruvector/vector-delta-tracker
+ */
+/** A single changed dimension in a vector update */
+export interface SparseChange {
+    index: number;
+    oldValue: number;
+    newValue: number;
+}
+/** A delta event representing a change to a pattern embedding */
+export interface PatternDelta {
+    patternId: string;
+    version: number;
+    timestamp: number;
+    deltaType: 'genesis' | 'update' | 'rollback';
+    sparseChanges: SparseChange[];
+    metadata?: Record<string, unknown>;
+    compressedSize?: number;
+}
+/** A full vector snapshot at a specific version */
+export interface DeltaSnapshot {
+    patternId: string;
+    version: number;
+    fullVector: number[];
+    timestamp: number;
+}
+/** Configuration for the VectorDeltaTracker */
+export interface VectorDeltaTrackerConfig {
+    /** Max deltas to retain per pattern (default: 50) */
+    maxHistoryPerPattern: number;
+    /** Full snapshot every N deltas (default: 10) */
+    snapshotInterval: number;
+    /** Buffer deltas before flushing (default: 20) */
+    batchSize: number;
+    /** Min absolute diff to count as changed (default: 1e-7) */
+    epsilon: number;
+}
+/** Summary statistics */
+export interface VectorDeltaTrackerStats {
+    totalPatterns: number;
+    totalDeltas: number;
+    avgDeltasPerPattern: number;
+}
+/**
+ * Tracks pattern embedding version history using sparse delta encoding.
+ * Genesis creates a v0 snapshot; subsequent updates store only changed dims.
+ * Periodic snapshots enable fast reconstruction via nearest-snapshot + replay.
+ */
+export declare class VectorDeltaTracker {
+    private readonly config;
+    private readonly history;
+    private readonly snapshots;
+    private readonly versions;
+    private readonly buffer;
+    constructor(config?: Partial<VectorDeltaTrackerConfig>);
+    /** Create v0 genesis. All dimensions stored as changes from zero vector. */
+    recordGenesis(patternId: string, vector: number[], metadata?: Record<string, unknown>): PatternDelta;
+    /** Record a sparse delta between old and new vectors. */
+    recordDelta(patternId: string, oldVector: number[], newVector: number[], metadata?: Record<string, unknown>): PatternDelta;
+    /** Get delta history for a pattern, newest first. */
+    getHistory(patternId: string, limit?: number): PatternDelta[];
+    /** Rollback to a version. Returns null if version does not exist. */
+    rollback(patternId: string, targetVersion: number): DeltaSnapshot | null;
+    /** Current version for a pattern (-1 if unknown). */
+    getVersion(patternId: string): number;
+    /** Rebuild full vector at a version via nearest snapshot + forward replay. */
+    reconstructAtVersion(patternId: string, version: number): number[] | null;
+    /** Remove old deltas beyond retention limit. Returns count pruned. */
+    pruneHistory(patternId: string, keepVersions?: number): number;
+    /** Summary statistics. */
+    getStats(): VectorDeltaTrackerStats;
+    /** Flush write batch. Returns buffered deltas and clears the buffer. */
+    flush(): PatternDelta[];
+    /** Number of buffered (unflushed) deltas. */
+    getBufferSize(): number;
+    /** Clear all data. */
+    clear(): void;
+    private computeSparseChanges;
+    private applySparseForward;
+    private enforceRetention;
+    private getOrCreate;
+}
+/**
+ * Create a VectorDeltaTracker instance.
+ * Returns null if useDeltaEventSourcing feature flag is disabled.
+ */
+export declare function createVectorDeltaTracker(config?: Partial<VectorDeltaTrackerConfig>): VectorDeltaTracker | null;
+//# sourceMappingURL=vector-delta-tracker.d.ts.map

package/dist/integrations/ruvector/vector-delta-tracker.js

@@ -0,0 +1,226 @@
+/**
+ * R3: Sparse Vector Delta Event Sourcing (ADR-087, Milestone 1)
+ *
+ * Tracks pattern embedding version history using sparse delta encoding.
+ * Only changed dimensions are stored, giving massive compression for
+ * typical pattern updates where few dimensions change.
+ *
+ * Storage: In-memory (Map-based). SQLite integration deferred to later task.
+ *
+ * @module integrations/ruvector/vector-delta-tracker
+ */
+import { isDeltaEventSourcingEnabled } from './feature-flags.js';
+const DEFAULT_CONFIG = {
+    maxHistoryPerPattern: 50,
+    snapshotInterval: 10,
+    batchSize: 20,
+    epsilon: 1e-7,
+};
+// ============================================================================
+// VectorDeltaTracker
+// ============================================================================
+/**
+ * Tracks pattern embedding version history using sparse delta encoding.
+ * Genesis creates a v0 snapshot; subsequent updates store only changed dims.
+ * Periodic snapshots enable fast reconstruction via nearest-snapshot + replay.
+ */
+export class VectorDeltaTracker {
+    config;
+    history = new Map();
+    snapshots = new Map();
+    versions = new Map();
+    buffer = [];
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /** Create v0 genesis. All dimensions stored as changes from zero vector. */
+    recordGenesis(patternId, vector, metadata) {
+        if (this.versions.has(patternId)) {
+            throw new Error(`Genesis already exists for pattern ${patternId} (version ${this.versions.get(patternId)})`);
+        }
+        const sparseChanges = this.computeSparseChanges(new Array(vector.length).fill(0), vector);
+        const delta = {
+            patternId, version: 0, timestamp: Date.now(),
+            deltaType: 'genesis', sparseChanges, metadata,
+            compressedSize: sparseChanges.length,
+        };
+        const snapshot = {
+            patternId, version: 0,
+            fullVector: [...vector], timestamp: delta.timestamp,
+        };
+        this.versions.set(patternId, 0);
+        this.getOrCreate(this.history, patternId).push(delta);
+        this.getOrCreate(this.snapshots, patternId).push(snapshot);
+        this.buffer.push(delta);
+        return delta;
+    }
+    /** Record a sparse delta between old and new vectors. */
+    recordDelta(patternId, oldVector, newVector, metadata) {
+        const cur = this.versions.get(patternId);
+        if (cur === undefined) {
+            throw new Error(`No genesis found for pattern ${patternId}. Call recordGenesis() first.`);
+        }
+        const nextVersion = cur + 1;
+        const sparseChanges = this.computeSparseChanges(oldVector, newVector);
+        const delta = {
+            patternId, version: nextVersion, timestamp: Date.now(),
+            deltaType: 'update', sparseChanges, metadata,
+            compressedSize: sparseChanges.length,
+        };
+        this.versions.set(patternId, nextVersion);
+        this.getOrCreate(this.history, patternId).push(delta);
+        this.buffer.push(delta);
+        if (nextVersion % this.config.snapshotInterval === 0) {
+            this.getOrCreate(this.snapshots, patternId).push({
+                patternId, version: nextVersion,
+                fullVector: [...newVector], timestamp: delta.timestamp,
+            });
+        }
+        this.enforceRetention(patternId);
+        return delta;
+    }
+    /** Get delta history for a pattern, newest first. */
+    getHistory(patternId, limit) {
+        const deltas = this.history.get(patternId);
+        if (!deltas || deltas.length === 0)
+            return [];
+        const reversed = [...deltas].reverse();
+        return (limit !== undefined && limit > 0) ? reversed.slice(0, limit) : reversed;
+    }
+    /** Rollback to a version. Returns null if version does not exist. */
+    rollback(patternId, targetVersion) {
+        const vector = this.reconstructAtVersion(patternId, targetVersion);
+        if (vector === null)
+            return null;
+        return { patternId, version: targetVersion, fullVector: vector, timestamp: Date.now() };
+    }
+    /** Current version for a pattern (-1 if unknown). */
+    getVersion(patternId) {
+        return this.versions.get(patternId) ?? -1;
+    }
+    /** Rebuild full vector at a version via nearest snapshot + forward replay. */
+    reconstructAtVersion(patternId, version) {
+        const deltas = this.history.get(patternId);
+        if (!deltas || deltas.length === 0)
+            return null;
+        const cur = this.versions.get(patternId);
+        if (version < 0 || version > cur)
+            return null;
+        const snaps = this.snapshots.get(patternId) || [];
+        let base = null;
+        for (let i = snaps.length - 1; i >= 0; i--) {
+            if (snaps[i].version <= version) {
+                base = snaps[i];
+                break;
+            }
+        }
+        if (!base)
+            return null;
+        const vector = [...base.fullVector];
+        const start = base.version + 1;
+        for (const d of deltas) {
+            if (d.version < start)
+                continue;
+            if (d.version > version)
+                break;
+            this.applySparseForward(vector, d.sparseChanges);
+        }
+        return vector;
+    }
+    /** Remove old deltas beyond retention limit. Returns count pruned. */
+    pruneHistory(patternId, keepVersions) {
+        const maxKeep = keepVersions ?? this.config.maxHistoryPerPattern;
+        const deltas = this.history.get(patternId);
+        if (!deltas || deltas.length <= maxKeep)
+            return 0;
+        const pruneCount = deltas.length - maxKeep;
+        const pruned = deltas.slice(0, pruneCount);
+        const kept = deltas.slice(pruneCount);
+        // Always preserve genesis
+        const gi = pruned.findIndex(d => d.deltaType === 'genesis');
+        if (gi >= 0) {
+            kept.unshift(pruned[gi]);
+            pruned.splice(gi, 1);
+        }
+        this.history.set(patternId, kept);
+        // Prune old snapshots (keep genesis + those >= oldest kept version)
+        const oldest = kept[0]?.version ?? 0;
+        const snaps = this.snapshots.get(patternId);
+        if (snaps) {
+            this.snapshots.set(patternId, snaps.filter(s => s.version === 0 || s.version >= oldest));
+        }
+        return pruned.length;
+    }
+    /** Summary statistics. */
+    getStats() {
+        let totalDeltas = 0;
+        for (const d of this.history.values())
+            totalDeltas += d.length;
+        const totalPatterns = this.history.size;
+        return {
+            totalPatterns, totalDeltas,
+            avgDeltasPerPattern: totalPatterns > 0 ? totalDeltas / totalPatterns : 0,
+        };
+    }
+    /** Flush write batch. Returns buffered deltas and clears the buffer. */
+    flush() {
+        const flushed = [...this.buffer];
+        this.buffer.length = 0;
+        return flushed;
+    }
+    /** Number of buffered (unflushed) deltas. */
+    getBufferSize() { return this.buffer.length; }
+    /** Clear all data. */
+    clear() {
+        this.history.clear();
+        this.snapshots.clear();
+        this.versions.clear();
+        this.buffer.length = 0;
+    }
+    // --------------------------------------------------------------------------
+    // Private
+    // --------------------------------------------------------------------------
+    computeSparseChanges(old, cur) {
+        const changes = [];
+        const len = Math.max(old.length, cur.length);
+        for (let i = 0; i < len; i++) {
+            const ov = i < old.length ? old[i] : 0;
+            const nv = i < cur.length ? cur[i] : 0;
+            if (Math.abs(ov - nv) > this.config.epsilon) {
+                changes.push({ index: i, oldValue: ov, newValue: nv });
+            }
+        }
+        return changes;
+    }
+    applySparseForward(vector, changes) {
+        for (const c of changes) {
+            while (vector.length <= c.index)
+                vector.push(0);
+            vector[c.index] = c.newValue;
+        }
+    }
+    enforceRetention(patternId) {
+        this.pruneHistory(patternId, this.config.maxHistoryPerPattern);
+    }
+    getOrCreate(map, key) {
+        let arr = map.get(key);
+        if (!arr) {
+            arr = [];
+            map.set(key, arr);
+        }
+        return arr;
+    }
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create a VectorDeltaTracker instance.
+ * Returns null if useDeltaEventSourcing feature flag is disabled.
+ */
+export function createVectorDeltaTracker(config) {
+    if (!isDeltaEventSourcingEnabled())
+        return null;
+    return new VectorDeltaTracker(config);
+}
+//# sourceMappingURL=vector-delta-tracker.js.map