v0.10.1 - CLI, Observability & Modular Server

Highlights

This release includes significant infrastructure improvements, observability features, and a modular server architecture refactor.

🔧 Breaking Changes

See MIGRATION.md for upgrade instructions.

• client: Remove deprecated ClusterClient.sendMessage() - use send(data, key) instead
• core: Remove legacy constructor from QueryOptimizer - use options object
• core: Remove legacy array format from CRDTDebugger.importHistory() - use v1.0 format

✨ New Features

Observability & Debugging

• CRDTDebugger - Full CRDT operation recording, replay, conflict detection, and export (JSON/CSV/NDJSON)
• SearchDebugger - BM25 TF-IDF breakdown, RRF rank contributions, timing analysis
• PrometheusExporter - Comprehensive metrics: connections, operations, CRDT merges, sync, cluster, storage, queries
• Grafana Dashboard - Pre-built dashboard JSON for TopGun monitoring

Admin Dashboard

• SetupWizard - 6-step guided setup for new deployments
• DataExplorer - Browse and edit map data with JSON editor
• QueryPlayground - Monaco editor with Cmd+Enter execution
• ClusterTopology - Visual cluster ring and partition distribution
• CommandPalette - Cmd+K quick navigation
• Settings - Hot-reloadable runtime configuration
• Login/Auth - JWT-based admin authentication

Distributed Search & Subscriptions

• ClusterSearchCoordinator - Scatter-gather distributed FTS with RRF merge
• DistributedSubscriptionCoordinator - Live query subscriptions across cluster nodes
• QueryCursor - Cursor-based pagination for distributed queries
• SearchCursor - Cursor-based pagination for distributed search

CLI & Developer Experience

• CLI Commands - topgun doctor, setup, dev, test, config, cluster, debug:crdt, debug:search
• BetterSqlite3Adapter - SQLite storage adapter for server-side persistence
• DevContainer - VS Code/Codespaces development environment
• Docker Compose Profiles - admin, monitoring, dbtools profiles

🔨 Changed

• server: Refactor DistributedSubscriptionCoordinator into focused coordinators (Base, Search, Query)
• server: Wire SearchCoordinator.dispose() into LifecycleManager for timer cleanup
• server: Extract handlers from ServerCoordinator into domain modules
• core: Split schemas.ts (1160 lines) into domain-focused modules
• core: Structured logging with pino throughout codebase

🗑️ Removed

• Dead code from ServerCoordinator (~1,263 lines)
• Phase/Spec/Bug references from code comments (488 occurrences)
• jest.retryTimes from flaky tests (proper fixes applied)

🐛 Fixed

• Timer cleanup in SearchCoordinator preventing memory leaks
• Type safety improvements across client message handlers
• WebCrypto polyfill for consistent test environment
• Use ServerFactory.create() instead of new ServerCoordinator()

🧪 Tests

• CLI command tests (28 tests covering all commands)
• 1814 tests in core package
• Cluster E2E tests for partition routing, node failure, replication

---

Full Changelog: v0.10.0...v0.10.1

v0.10.0 - Distributed Live Subscriptions

Distributed Live Subscriptions

This release introduces distributed live subscriptions - real-time queries and full-text search that work across all cluster nodes.

Features

• Distributed Query Subscriptions: query().subscribe() aggregates results from all cluster nodes
• Distributed Search Subscriptions: searchSubscribe() returns real-time results with RRF merging
• Coordinator Pattern: Efficient subscription management - updates flow only to relevant coordinators
• Delta Updates: ENTER/UPDATE/LEAVE events minimize network traffic
• Automatic Failover: Node disconnects handled gracefully
• Cursor-Based Pagination: New cursor API for stable pagination

New Prometheus Metrics

topgun_distributed_sub_active{type="SEARCH|QUERY"}
topgun_distributed_sub_total{type,status}
topgun_distributed_sub_updates{direction,change_type}

Documentation

• Live Queries Guide
• Full-Text Search Guide
• Cluster Replication Guide
• Blog Post

Installation

npm install @topgunbuild/core @topgunbuild/client @topgunbuild/server

Full Changelog: v0.9.0...v0.10.0

v0.9.0

What's New

MCP Server Package 🤖

New @topgunbuild/mcp-server package enables AI assistants like Claude Desktop and Cursor to interact with TopGun databases through the Model Context Protocol (MCP).

Features:

• Query, mutate, and search data using natural language
• Full-text hybrid search (BM25 + exact matching)
• Real-time subscriptions for watching changes
• Schema inspection and query explanation
• HTTP and stdio transports
• Security controls: restricted maps, read-only mode, auth tokens

Quick Start:

{
  "mcpServers": {
    "topgun": {
      "command": "npx",
      "args": ["@topgunbuild/mcp-server"],
      "env": {
        "TOPGUN_URL": "ws://localhost:8080"
      }
    }
  }
}

Documentation

• Added comprehensive MCP Server guide to documentation site

Commits

• feat(mcp-server): add MCP Server package for AI assistant integration
• refactor(mcp-server): add Zod validation and pino logger
• chore: bump version to 0.9.0 and add MCP Server documentation

Full Changelog: v0.8.1...v0.9.0

v0.8.1 - Hybrid Search

Phase 12: Hybrid Search with RRF Fusion

Features

• Reciprocal Rank Fusion (RRF) for merging search results from multiple sources
• QueryExecutor with parallel FTS + filter execution
• LiveFTSIndex for live hybrid query updates
• HybridQueryHandle for client-side hybrid queries
• useHybridQuery React hook for faceted search UIs
• _score sorting for relevance-based results

New APIs

Client:

const handle = client.hybridQuery<Article>('articles', {
  predicate: Predicates.and(
    Predicates.match('body', 'machine learning'),
    Predicates.equal('category', 'tech')
  ),
  sort: { _score: 'desc' },
  limit: 20
});

React:

const { results, loading } = useHybridQuery<Article>('articles', {
  predicate: Predicates.match('body', 'machine learning'),
  sort: { _score: 'desc' }
});

Predicates

Type	Predicates
FTS	match(), matchPhrase(), matchPrefix()
Filters	eq(), gt(), lt(), gte(), lte(), contains()
Logical	and(), or()

Installation

npm install @topgunbuild/client @topgunbuild/react

Documentation

• Hybrid Queries Guide
• useHybridQuery Reference

v0.8.0 - Full-Text Search

What's New

Phase 11: Full-Text Search (FTS)

This release introduces a complete full-text search solution with BM25 relevance ranking and real-time updates.

Features

• BM25 Ranked Search - Industry-standard relevance algorithm with Porter stemming and 174 English stopwords
• Server-side FTS Indexes - Centralized indexes with automatic updates on data changes
• Live Search Subscriptions - Real-time search results with delta updates (ENTER/UPDATE/LEAVE events)
• React useSearch Hook - Easy integration with debounce support for search-as-you-type UIs
• O(1) Live Updates - scoreSingleDocument optimization for 1000x faster live search updates
• Notification Batching - 16ms batching window to prevent update storms

New APIs

Server Configuration

```typescript
const server = new ServerCoordinator({
fullTextSearch: {
articles: {
fields: ['title', 'body'],
tokenizer: { minLength: 2 },
bm25: { k1: 1.2, b: 0.75 }
}
}
});
```

Client Search

```typescript
// One-shot search
const results = await client.search('articles', 'machine learning', {
limit: 20,
boost: { title: 2.0 }
});

// Live search subscription
const handle = client.searchSubscribe('articles', 'machine learning');
handle.subscribe((results) => {
console.log('Results updated:', results);
});
```

React Hook

```typescript
const { results, loading, error } = useSearch('articles', searchTerm, {
debounceMs: 300,
limit: 20
});
```

Performance Improvements

Metric	Before	After	Improvement
scoreDocument (1K docs)	~10ms	~0.01ms	1000×
scoreDocument (10K docs)	~100ms	~0.01ms	10000×

Documentation

• Full-Text Search Guide
• React Hooks Reference

Breaking Changes

None. This is a backwards-compatible feature release.

---

Full Changelog: v0.7.0...v0.8.0

v0.7.0 - Phase 10 Cluster Enhancements

Phase 10: Cluster Enhancements

This release adds comprehensive cluster replication and failover capabilities.

✨ New Features

Cluster Replication

• ReplicationPipeline: Async and sync replication with configurable consistency levels (EVENTUAL, QUORUM, STRONG)
• Gossip Protocol: Automatic cluster member discovery via gossip-based protocol
• Partition-aware routing: Direct operations to partition owners with smart routing

Anti-Entropy Repair

• MerkleTreeManager: Efficient hash-based data verification using Merkle trees
• RepairScheduler: Automated periodic repair with configurable scan intervals
• Bucket-level comparison: Minimizes network traffic by drilling down to divergent buckets

Failover Handling

• PartitionReassigner: Automatic partition rebalancing on node failure
• Phi Accrual Failure Detector: Adaptive failure detection that avoids false positives
• ReadReplicaHandler: Support for reading from replica nodes for lower latency

📚 Documentation

• New "Cluster Replication" guide covering setup, consistency levels, and best practices
• Updated sidebar navigation and Prev/Next links

🧪 Tests

• 38 E2E cluster tests covering replication, failover, and partition routing
• Unit tests for all new cluster components

📦 Packages Updated

• @topgunbuild/core → 0.7.0
• @topgunbuild/client → 0.7.0
• @topgunbuild/server → 0.7.0
• @topgunbuild/adapters → 0.7.0
• @topgunbuild/react → 0.7.0
• @topgunbuild/native → 0.7.0
• @topgunbuild/adapter-better-auth → 0.7.0

v0.6.0 - Phase 9 Query Engine Enhancements

New Features

Lazy Index Building (Phase 9.01)

• LazyHashIndex, LazyNavigableIndex, LazyInvertedIndex classes
• Deferred index construction until first query for fast startup
• Progress callbacks for index materialization
• lazyIndexBuilding option in IndexedLWWMap

Attribute Factory (Phase 9.02)

• generateAttributes<V>() with curried type inference
• attr() and multiAttr() helper functions
• createSchema<V>() fluent builder
• Nested path support (e.g., 'address.city')

Compound Index Auto-Detection (Phase 9.03)

• CompoundIndex class for multi-attribute O(1) lookups
• Compound query tracking in QueryPatternTracker
• Compound index suggestions in IndexAdvisor
• Automatic CompoundIndex usage in QueryOptimizer

Tests

• 140+ new tests for Phase 9 features
• 1264 total tests in core package

Installation

npm install @topgunbuild/core@0.6.0
npm install @topgunbuild/client@0.6.0
npm install @topgunbuild/server@0.6.0

v0.5.0 - Query Engine & Adaptive Indexing

What's New in v0.5.0

This release introduces a powerful Query Engine with index-based retrieval, enabling sub-millisecond queries on large datasets.

Query Engine (Phase 7)

• HashIndex - O(1) equality lookups
• NavigableIndex - O(log N) range queries with SkipList-based SortedMap
• QueryOptimizer - Cost-based query planning with automatic index selection
• StandingQueryIndex - Pre-computed results for live queries
• ResultSet Pipeline - Lazy, composable query results

Full-Text Search (Phase 8.01)

• InvertedIndex - Token-based indexing for text search
• New query predicates: `contains`, `containsAll`, `containsAny`
• Configurable tokenization with filters (lowercase, stop words, min length)
• Multi-value attribute support

Adaptive Indexing (Phase 8.02)

• QueryPatternTracker - Runtime statistics collection
• IndexAdvisor - Intelligent index suggestions based on query patterns
• AutoIndexManager - Optional automatic index creation
• DefaultIndexingStrategy - Auto-index scalar fields

New Classes

• `IndexedLWWMap` - LWWMap with index support
• `IndexedORMap` - ORMap with index support

Performance

• Equality queries: 100-1000× faster than full scan
• Range queries: O(log N) instead of O(N)
• Text search: Sub-millisecond on 100K+ documents

Documentation

• New guides: Indexing, Full-Text Search, Adaptive Indexing
• Comprehensive API documentation
• Benchmark results and recommendations

Breaking Changes

None - this release is fully backward compatible.

Installation

```bash
npm install @topgunbuild/core@0.5.0
npm install @topgunbuild/client@0.5.0
npm install @topgunbuild/server@0.5.0
```

Quick Start

```typescript
import { IndexedLWWMap, HLC, simpleAttribute, Predicates } from '@topgunbuild/core';

const hlc = new HLC('node-1');
const users = new IndexedLWWMap<string, User>(hlc);

// Add indexes
users.addHashIndex(simpleAttribute('email', u => u.email));
users.addNavigableIndex(simpleAttribute('age', u => u.age));
users.addInvertedIndex(simpleAttribute('bio', u => u.bio));

// Query with indexes
const results = users.query(
Predicates.and(
Predicates.equal('status', 'active'),
Predicates.between('age', 25, 35),
Predicates.contains('bio', 'developer')
)
);
```

v0.4.0 - Phase 5 Features

What's New in v0.4.0

This release completes Phase 5 of the TopGun roadmap, adding powerful new CRDTs, server-side processing capabilities, and improved synchronization.

New CRDTs and Data Structures

• PN Counter - Positive-Negative counter CRDT supporting increment/decrement operations with eventual consistency
• Event Journal - Append-only event log for event sourcing patterns with full CRDT synchronization
• Entry Processor - Atomic server-side map operations with sandboxed execution via isolated-vm

API Enhancements

• Custom Conflict Resolvers - Register custom conflict resolution strategies for domain-specific merge logic
• Delta Updates for Subscriptions - Incremental updates instead of full data snapshots for improved performance
• Offline Persistence for PNCounter - Full offline support for counter operations

React Hooks

• usePNCounter - Hook for working with PN Counter in React applications
• useEventJournal - Hook for subscribing to Event Journal streams
• Enhanced useQuery with delta update support

Bug Fixes

• Fixed memory leak in React change tracking with new maxChanges option
• Fixed isolated-vm bundling issues for server package
• Added production warning when isolated-vm is unavailable

Documentation

• New guides for PNCounter, Entry Processor, Event Journal
• Conflict resolution blog post with ML/AI integration examples

---

Full Changelog: v0.3.0...v0.4.0

v0.3.0 - Clustering

What's New

Server Clustering

• ClusterCoordinator - Integration layer for coordinating server nodes
• ReplicationPipeline - Async cross-node data replication
• PartitionService - Consistent hashing with 271 partitions
• Gradual Rebalancing - Smooth topology changes without data loss

Client Clustering

• ClusterClient - Multi-node connection management with ConnectionPool
• PartitionRouter - Partition-aware request routing with metrics
• Failover Handling - Circuit breaker pattern for node failures
• IConnectionProvider - Abstraction for SyncEngine connection management

Split-Brain Protection

• FailureDetector - Phi Accrual algorithm for accurate failure detection
• FencingManager - Epoch-based partition fencing to prevent split-brain

Performance Improvements

• msgpackr - 2x throughput improvement over @msgpack/msgpack
• CoalescingWriter - Optimized maxDelayMs for lower latency
• k6 Load Testing - New test scenarios with MessagePack encoder

Breaking Changes

• TopGunClient now accepts cluster config option for multi-server mode
• Minimum Node.js version: 18.x

Packages

Package	Version
@topgunbuild/core	0.3.0
@topgunbuild/client	0.3.0
@topgunbuild/server	0.3.0
@topgunbuild/react	0.3.0
@topgunbuild/adapters	0.3.0

Installation

npm install @topgunbuild/client @topgunbuild/server

Documentation

• Cluster Client Guide
• API Reference