v0.13.0 — Data Platform (Intermediate)

Highlights

Unified Query API — client.query() now supports field projection, result limits, and efficient Merkle delta reconnect. The separate Shapes API has been removed — all partial replication features are unified under one API.

Schema System — TypeScript-first schema definition with server-side validation. Define schemas with @topgunbuild/schema, generate Rust validation code via CLI.

DataFusion SQL — SELECT, WHERE, GROUP BY, ORDER BY queries powered by Apache DataFusion (feature-gated: --features datafusion).

What's New

Features

• Unified Query API with fields projection, limit, Merkle delta reconnect, writer exclusion
• Schema system: DSL, codegen, server-side SchemaService
• DataFusion SQL integration: QueryBackend trait, Arrow cache, TopGunTableProvider
• RSA JWT auto-detection (HMAC vs RSA/EC)
• Simulation testing framework (SimCluster, SimNetwork, proptest)

Security

• Re-enabled JWT expiration validation with configurable leeway
• CORS origins default changed to empty (deny-all)
• Missing sub claim now rejected with AUTH_FAIL

Documentation

• New guides: Schema & Type Safety, SQL Queries, Troubleshooting, FAQ, Benchmarks
• New tutorials: Todo App with React + TopGun
• Updated Live Queries guide with field projection, limits, Merkle reconnect
• Fixed misleading auth/security/RBAC documentation
• Brand color token system for docs site

Breaking Changes

• subscribeShape() removed — use client.query() with fields option instead
• ShapeHandle, ShapeManager removed — QueryHandle now has all capabilities
• SHAPE_* wire messages removed — use QUERY_* with extended fields

Updated Packages

Package	Version
@topgunbuild/core	0.13.0
@topgunbuild/client	0.13.0
@topgunbuild/react	0.13.0

Stats

• 589 Rust server tests, 461 client tests, 57 integration tests — all passing
• 206 files changed, +32,112 / -1,697 lines since v0.12.0

v0.12.0 — Rust Server Migration

Highlights

TopGun v0.12.0 replaces the TypeScript server with a high-performance Rust implementation built on axum/tokio, while keeping the TypeScript client SDK fully compatible.

Live Demo — try real-time CRDT sync in your browser

What's new

Rust Server

• axum WebSocket server with tokio async runtime
• 7 domain services: CRDT, Sync, Query, Search, Messaging, Persistence, Coordination
• PostgreSQL storage via sqlx with automatic schema creation
• Cluster protocol with 271-partition data distribution
• Full-text search via tantivy
• Admin API with JWT authentication

Client Improvements

• Reconnection overhaul: unified backoff config, forceReconnect(), navigator.onLine listener for instant reconnect when network returns
• Heartbeat fix: timeout no longer permanently kills the connection
• IDBAdapter: IndexedDB persistence for true offline-first (data survives page refresh)
• Op-ack fix: numeric comparison instead of lexicographic string comparison

Sync Lab Demo

• Live CRDT conflict resolution demo at demo.topgun.build
• Embedded on topgun.build homepage
• Disconnect/reconnect testing with real offline persistence

Docs & Metadata

• 24 guides, 8 blog posts, full API reference at topgun.build/docs
• repository field added to all npm packages
• README updated for Rust server

Test Coverage

• 953 Rust tests (server + core)
• 2,052 TypeScript tests (client + core + react + adapters)
• 55 integration tests (TS client → Rust server)

Install

npm install @topgunbuild/client@0.12.0 @topgunbuild/adapters@0.12.0 @topgunbuild/react@0.12.0

Packages

Package	Version
@topgunbuild/core	0.12.0
@topgunbuild/client	0.12.0
@topgunbuild/adapters	0.12.0
@topgunbuild/react	0.12.0
@topgunbuild/adapter-better-auth	0.12.0
@topgunbuild/mcp-server	0.12.0

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')
)
);
```