refactor(8.0)!: remove distributed clustering subsystem — inert/orphaned, scale is single-process + native provider

The distributed-clustering subsystem never ran in production: it was inert,
orphaned dead code (faked consensus, stub replication, no live wiring, and it
did not interoperate with the 8.0 Db API). Brainy 8.0 is a single-process
library. Scale is single-process + the optional native provider
(@soulcraft/cortex, on-disk DiskANN to 10B+ vectors) + per-tenant pools +
horizontal read scaling (many reader processes, one writer).

Removed:
- src/distributed/ entirely (coordinator, shardManager, cacheSync,
  readWriteSeparation, queryPlanner, healthMonitor, configManager,
  hashPartitioner, shardMigration, domainDetector, storageDiscovery, http/network
  transports). ReaderMode/HybridMode relocated to src/storage/operationalModes.ts
  (slimmed to the live surface).
- src/types/distributedTypes.ts; config.distributed field + JSDoc;
  coreTypes distributedConfig; memoryStorage distributedConfig persistence.
- DistributedRole enum + src/config/distributedPresets.ts and the orphaned
  src/config/extensibleConfig.ts (config/augmentation registry built on removed
  cloud adapters + distributed presets), plus their src/index.ts re-exports.
- 13 BRAINY_* cluster env vars; the storage setDistributedComponents hook;
  enableDistributedSearch (dead config flag); the metadata partition field;
  the distributed_ reserved key prefix.
- Orphaned src/storage/readOnlyOptimizations.ts (zero importers).
- Tests targeting the subsystem: distributed-demo, distributed-cluster helper,
  distributed-transactions, sharding-transactions.
- Docs: EXTENDING_STORAGE.md (deleted); scrubbed distributed/cluster/Raft/
  shard-manager/multi-node prose from v3-features, enterprise-for-everyone,
  augmentations-actual, complete-feature-list, vfs/README, vfs/ROADMAP,
  vfs/VFS_CORE, capacity-planning, transactions, MIGRATION-V3-TO-V4,
  storage-architecture; reframed scale prose to the 8.0 model.

Kept: src/storage/sharding.ts (local-disk 256-bucket directory sharding via
getShardIdFromUuid — used live by baseStorage, unrelated to clustering);
the multi-process mode: 'reader' | 'writer' roles; semantic/HNSW clustering.

RELEASES.md: added a removed-surfaces row documenting the cut and the 8.0
scale model.
This commit is contained in:
David Snelling 2026-06-15 10:37:39 -07:00
parent f8e0079d3f
commit 00d3203d68
51 changed files with 153 additions and 9889 deletions

View file

@ -1,393 +0,0 @@
/**
* Distributed + Transactions Integration Tests
*
* Verifies that transactions work correctly with distributed storage:
* - Remote storage adapters (S3, Azure, GCS)
* - Distributed coordination
* - Cache coherence
* - Read/write separation
*/
import { describe, it, expect, beforeEach, afterEach } from 'vitest'
import { Brainy } from '../../../src/brainy.js'
import { NounType, VerbType } from '../../../src/types/graphTypes.js'
import { tmpdir } from 'os'
import { join } from 'path'
import { mkdirSync, rmSync } from 'fs'
describe('Transactions + Distributed Storage Integration', () => {
let brain: Brainy
let testDir: string
beforeEach(async () => {
testDir = join(tmpdir(), `brainy-distributed-test-${Date.now()}`)
mkdirSync(testDir, { recursive: true })
// Use filesystem as proxy for distributed storage
// (In production, this would be S3, Azure, GCS, etc.)
brain = new Brainy({ requireSubtype: false,
storage: {
type: 'filesystem',
path: testDir
}
})
await brain.init()
})
afterEach(async () => {
if (brain) {
await brain.shutdown()
}
if (testDir) {
rmSync(testDir, { recursive: true, force: true })
}
})
describe('Remote Storage Adapters', () => {
it('should handle transactions with filesystem storage (proxy for remote)', async () => {
// Add entity (atomic operation)
const id = await brain.add({
data: { name: 'Remote Entity', location: 'cloud' },
type: NounType.Thing
})
expect(id).toBeTruthy()
// Verify entity persisted to storage
const entity = await brain.get(id)
expect(entity).toBeTruthy()
expect(entity?.data.name).toBe('Remote Entity')
})
it('should rollback failed operations with remote storage', async () => {
// Add first entity (succeeds)
const id1 = await brain.add({
data: { name: 'Entity 1' },
type: NounType.Thing
})
// Attempt to add with invalid data (fails)
let failed = false
try {
await brain.add({
data: null as any,
type: NounType.Thing
})
} catch (e) {
failed = true
}
expect(failed).toBe(true)
// First entity should still exist
const entity1 = await brain.get(id1)
expect(entity1).toBeTruthy()
})
it('should handle update operations with remote storage atomically', async () => {
// Add entity
const id = await brain.add({
data: { name: 'Original', version: 1 },
type: NounType.Thing
})
// Update atomically
await brain.update({
id,
data: { name: 'Updated', version: 2 }
})
// Verify update persisted
const entity = await brain.get(id)
expect(entity?.data.version).toBe(2)
})
})
describe('Write Coordinator Atomicity', () => {
it('should ensure atomicity at write coordinator level', async () => {
// Simulate write coordinator scenario
// (Single Brainy instance coordinating writes)
const entities: string[] = []
// Multiple atomic writes
for (let i = 0; i < 5; i++) {
const id = await brain.add({
data: { name: `Entity ${i}`, index: i },
type: NounType.Thing
})
entities.push(id)
}
// Create relationships (atomic)
for (let i = 0; i < entities.length - 1; i++) {
await brain.relate({
from: entities[i],
to: entities[i + 1],
type: VerbType.RelatesTo
})
}
// Verify all operations succeeded
for (let i = 0; i < entities.length; i++) {
const entity = await brain.get(entities[i])
expect(entity).toBeTruthy()
expect(entity?.data.index).toBe(i)
}
// Verify relationships
for (let i = 0; i < entities.length - 1; i++) {
const relations = await brain.related({ from: entities[i] })
expect(relations).toHaveLength(1)
}
})
it('should handle batch operations atomically on write coordinator', async () => {
const batchSize = 20
const ids: string[] = []
// Batch add operations
for (let i = 0; i < batchSize; i++) {
const id = await brain.add({
data: { name: `Batch Entity ${i}`, batch: true },
type: NounType.Thing
})
ids.push(id)
}
// Verify all entities persisted
let count = 0
for (const id of ids) {
const entity = await brain.get(id)
if (entity) count++
}
expect(count).toBe(batchSize)
})
})
describe('Read-After-Write Consistency', () => {
it('should ensure read-after-write consistency', async () => {
// Write entity
const id = await brain.add({
data: { name: 'RAW Test', timestamp: Date.now() },
type: NounType.Thing
})
// Immediate read (should see the write)
const entity = await brain.get(id)
expect(entity).toBeTruthy()
expect(entity?.data.name).toBe('RAW Test')
})
it('should maintain consistency after update', async () => {
const id = await brain.add({
data: { name: 'Original', counter: 0 },
type: NounType.Thing
})
// Multiple updates
for (let i = 1; i <= 5; i++) {
await brain.update({
id,
data: { name: `Updated ${i}`, counter: i }
})
// Read immediately after each update
const entity = await brain.get(id)
expect(entity?.data.counter).toBe(i)
}
})
})
describe('Concurrent Write Handling', () => {
it('should handle sequential writes correctly', async () => {
const ids: string[] = []
// Sequential writes (simulating distributed writes to coordinator)
for (let i = 0; i < 10; i++) {
const id = await brain.add({
data: { name: `Sequential ${i}`, order: i },
type: NounType.Thing
})
ids.push(id)
}
// Verify all writes succeeded
for (let i = 0; i < ids.length; i++) {
const entity = await brain.get(ids[i])
expect(entity?.data.order).toBe(i)
}
})
it('should handle interleaved operations atomically', async () => {
// Create entities
const id1 = await brain.add({
data: { name: 'Entity A', value: 100 },
type: NounType.Thing
})
const id2 = await brain.add({
data: { name: 'Entity B', value: 200 },
type: NounType.Thing
})
// Interleaved updates
await brain.update({ id: id1, data: { value: 150 } })
await brain.update({ id: id2, data: { value: 250 } })
await brain.update({ id: id1, data: { value: 175 } })
// Verify final state
const entity1 = await brain.get(id1)
const entity2 = await brain.get(id2)
expect(entity1?.data.value).toBe(175)
expect(entity2?.data.value).toBe(250)
})
})
describe('Delete Operations with Distributed Storage', () => {
it('should handle delete operations atomically', async () => {
// Create entity
const id = await brain.add({
data: { name: 'To Delete', status: 'active' },
type: NounType.Thing
})
// Verify exists
let entity = await brain.get(id)
expect(entity).toBeTruthy()
// Delete atomically
await brain.remove(id)
// Verify deleted
entity = await brain.get(id)
expect(entity).toBeNull()
})
it('should handle delete with relationships atomically', async () => {
// Create entities and relationships
const id1 = await brain.add({
data: { name: 'Entity 1' },
type: NounType.Thing
})
const id2 = await brain.add({
data: { name: 'Entity 2' },
type: NounType.Thing
})
await brain.relate({
from: id1,
to: id2,
type: VerbType.RelatesTo
})
// Delete first entity (should delete relationships)
await brain.remove(id1)
// Verify entity deleted
const entity1 = await brain.get(id1)
expect(entity1).toBeNull()
// Verify relationships deleted
const relations = await brain.related({ from: id1 })
expect(relations).toHaveLength(0)
// Entity 2 should still exist
const entity2 = await brain.get(id2)
expect(entity2).toBeTruthy()
})
})
describe('Storage Adapter Transparency', () => {
it('should work transparently with any storage adapter', async () => {
// This test verifies that transactions don't make assumptions
// about the underlying storage implementation
// Add entity
const id = await brain.add({
data: { name: 'Adapter Test', adapter: 'filesystem' },
type: NounType.Thing
})
// Update entity
await brain.update({
id,
data: { name: 'Updated via Adapter', adapter: 'filesystem' }
})
// Query entity
const entity = await brain.get(id)
expect(entity).toBeTruthy()
expect(entity?.data.name).toBe('Updated via Adapter')
// Delete entity
await brain.remove(id)
const deletedEntity = await brain.get(id)
expect(deletedEntity).toBeNull()
})
it('should maintain atomicity regardless of storage latency', async () => {
// Simulate scenario with storage latency
// (In distributed setup, network latency is a factor)
const startTime = Date.now()
// Operations that might have latency
const id1 = await brain.add({
data: { name: 'Latency Test 1' },
type: NounType.Thing
})
const id2 = await brain.add({
data: { name: 'Latency Test 2' },
type: NounType.Thing
})
await brain.relate({
from: id1,
to: id2,
type: VerbType.RelatesTo
})
const endTime = Date.now()
const duration = endTime - startTime
// Verify all operations succeeded (regardless of latency)
const entity1 = await brain.get(id1)
const entity2 = await brain.get(id2)
const relations = await brain.related({ from: id1 })
expect(entity1).toBeTruthy()
expect(entity2).toBeTruthy()
expect(relations).toHaveLength(1)
// Should complete in reasonable time (even with storage latency)
expect(duration).toBeLessThan(5000)
})
})
describe('Transaction Statistics with Distributed Storage', () => {
it('should track transaction statistics accurately', async () => {
// Get transaction manager stats
const stats = (brain as any).transactionManager?.getStats()
if (stats) {
const initialTotal = stats.totalTransactions
// Perform operations
await brain.add({
data: { name: 'Stats Test' },
type: NounType.Thing
})
// Check stats updated
const updatedStats = (brain as any).transactionManager?.getStats()
expect(updatedStats.totalTransactions).toBeGreaterThan(initialTotal)
}
})
})
})

View file

@ -1,295 +0,0 @@
/**
* Sharding + Transactions Integration Tests
*
* Verifies that transactions work correctly with sharded storage:
* - Cross-shard atomicity
* - Shard-aware routing
* - Rollback across shards
* - UUID-based shard distribution
*/
import { describe, it, expect, beforeEach, afterEach } from 'vitest'
import { Brainy } from '../../../src/brainy.js'
import { NounType, VerbType } from '../../../src/types/graphTypes.js'
import { tmpdir } from 'os'
import { join } from 'path'
import { mkdirSync, rmSync } from 'fs'
describe('Transactions + Sharding Integration', () => {
let brain: Brainy
let testDir: string
beforeEach(async () => {
testDir = join(tmpdir(), `brainy-shard-test-${Date.now()}`)
mkdirSync(testDir, { recursive: true })
brain = new Brainy({ requireSubtype: false,
storage: {
type: 'filesystem',
path: testDir
}
})
await brain.init()
})
afterEach(async () => {
if (brain) {
await brain.shutdown()
}
if (testDir) {
rmSync(testDir, { recursive: true, force: true })
}
})
describe('Cross-Shard Operations', () => {
it('should handle atomic operations across multiple shards', async () => {
// Create entities with different UUID prefixes (different shards)
const id1 = 'aaa00000-1111-4111-8111-111111111111' // Shard: aaa
const id2 = 'bbb00000-2222-4222-8222-222222222222' // Shard: bbb
// Add entities to different shards (atomic)
await brain.add({
id: id1,
data: { name: 'Entity in Shard A', shard: 'aaa' },
type: NounType.Thing
})
await brain.add({
id: id2,
data: { name: 'Entity in Shard B', shard: 'bbb' },
type: NounType.Thing
})
// Create relationship across shards (atomic)
const relationId = await brain.relate({
from: id1,
to: id2,
type: VerbType.RelatesTo
})
// Verify all entities exist
const entity1 = await brain.get(id1)
const entity2 = await brain.get(id2)
const relations = await brain.related({ from: id1 })
expect(entity1).toBeTruthy()
expect(entity2).toBeTruthy()
expect(relations).toHaveLength(1)
expect(relations[0].targetId).toBe(id2)
})
it('should rollback operations across multiple shards', async () => {
const id1 = 'ccc00000-1111-4111-8111-111111111111' // Shard: ccc
const id2 = 'ddd00000-2222-4222-8222-222222222222' // Shard: ddd
// Add first entity (succeeds)
await brain.add({
id: id1,
data: { name: 'Entity in Shard C' },
type: NounType.Thing
})
// Attempt to add second entity with invalid data (fails)
let failed = false
try {
await brain.add({
id: id2,
data: null as any, // Invalid
type: NounType.Thing
})
} catch (e) {
failed = true
}
expect(failed).toBe(true)
// First entity should still exist (in shard C)
const entity1 = await brain.get(id1)
expect(entity1).toBeTruthy()
// Second entity should not exist (rollback in shard D)
const entity2 = await brain.get(id2)
expect(entity2).toBeNull()
})
it('should handle updates across shards atomically', async () => {
const id1 = 'eee00000-1111-4111-8111-111111111111'
const id2 = 'fff00000-2222-4222-8222-222222222222'
// Add entities
await brain.add({
id: id1,
data: { name: 'Original E', version: 1 },
type: NounType.Thing
})
await brain.add({
id: id2,
data: { name: 'Original F', version: 1 },
type: NounType.Thing
})
// Update both entities (different shards)
await brain.update({
id: id1,
data: { name: 'Updated E', version: 2 }
})
await brain.update({
id: id2,
data: { name: 'Updated F', version: 2 }
})
// Verify updates in both shards
const entity1 = await brain.get(id1)
const entity2 = await brain.get(id2)
expect(entity1?.data.version).toBe(2)
expect(entity2?.data.version).toBe(2)
})
})
describe('Shard Distribution', () => {
it('should distribute entities across shards based on UUID', async () => {
// Create entities with various UUID prefixes
const ids = [
'aaa00000-1111-4111-8111-111111111111',
'bbb00000-2222-4222-8222-222222222222',
'ccc00000-3333-4333-8333-333333333333',
'ddd00000-4444-4444-8444-444444444444'
]
// Add entities to different shards
for (let i = 0; i < ids.length; i++) {
await brain.add({
id: ids[i],
data: { name: `Entity ${i}`, index: i },
type: NounType.Thing
})
}
// Verify all entities can be retrieved (regardless of shard)
for (let i = 0; i < ids.length; i++) {
const entity = await brain.get(ids[i])
expect(entity).toBeTruthy()
expect(entity?.data.index).toBe(i)
}
})
it('should handle relationships between different shard combinations', async () => {
const entities = [
{ id: 'aaa00000-1111-4111-8111-111111111111', name: 'A' },
{ id: 'bbb00000-2222-4222-8222-222222222222', name: 'B' },
{ id: 'ccc00000-3333-4333-8333-333333333333', name: 'C' }
]
// Add all entities
for (const e of entities) {
await brain.add({
id: e.id,
data: { name: e.name },
type: NounType.Thing
})
}
// Create relationships across all shards
await brain.relate({
from: entities[0].id,
to: entities[1].id,
type: VerbType.RelatesTo
})
await brain.relate({
from: entities[1].id,
to: entities[2].id,
type: VerbType.RelatesTo
})
await brain.relate({
from: entities[2].id,
to: entities[0].id,
type: VerbType.RelatesTo
})
// Verify all relationships exist
const relations0 = await brain.related({ from: entities[0].id })
const relations1 = await brain.related({ from: entities[1].id })
const relations2 = await brain.related({ from: entities[2].id })
expect(relations0).toHaveLength(1)
expect(relations1).toHaveLength(1)
expect(relations2).toHaveLength(1)
})
})
describe('Delete Operations Across Shards', () => {
it('should delete entities and relationships across shards atomically', async () => {
const id1 = 'ggg00000-1111-4111-8111-111111111111'
const id2 = 'hhh00000-2222-4222-8222-222222222222'
// Add entities in different shards
await brain.add({
id: id1,
data: { name: 'Entity G' },
type: NounType.Thing
})
await brain.add({
id: id2,
data: { name: 'Entity H' },
type: NounType.Thing
})
// Create relationship
await brain.relate({
from: id1,
to: id2,
type: VerbType.RelatesTo
})
// Delete first entity (should also delete relationship)
await brain.remove(id1)
// Verify entity deleted from shard G
const entity1 = await brain.get(id1)
expect(entity1).toBeNull()
// Entity H should still exist in shard H
const entity2 = await brain.get(id2)
expect(entity2).toBeTruthy()
// Relationship should be deleted
const relations = await brain.related({ from: id1 })
expect(relations).toHaveLength(0)
})
})
describe('Batch Operations Across Shards', () => {
it('should handle batch adds across multiple shards atomically', async () => {
const entities = [
{ id: 'shard1-00-1111-4111-8111-111111111111', data: { name: 'S1-E1' } },
{ id: 'shard2-00-2222-4222-8222-222222222222', data: { name: 'S2-E1' } },
{ id: 'shard3-00-3333-4333-8333-333333333333', data: { name: 'S3-E1' } },
{ id: 'shard1-00-4444-4444-8444-444444444444', data: { name: 'S1-E2' } },
{ id: 'shard2-00-5555-4555-8555-555555555555', data: { name: 'S2-E2' } }
]
// Add all entities (distributed across shards)
for (const e of entities) {
await brain.add({
id: e.id,
data: e.data,
type: NounType.Thing
})
}
// Verify all entities exist in their respective shards
for (const e of entities) {
const entity = await brain.get(e.id)
expect(entity).toBeTruthy()
expect(entity?.data.name).toBe(e.data.name)
}
})
})
})