fix: resolve v5.7.0 deadlock by restoring storage layer separation (v5.7.1)
CRITICAL BUG FIX - v5.7.0 caused complete production failure PROBLEM: v5.7.0 introduced circular dependency deadlock during GraphAdjacencyIndex initialization: GraphAdjacencyIndex.rebuild() → storage.getVerbs() → getVerbsBySource_internal() → getGraphIndex() [NEW in v5.7.0] → [waiting for rebuild to complete] → DEADLOCK SYMPTOMS (Production Impact): - ALL imports hung at "Reading Data Structure" for 760+ seconds - brain.add() operations took 12+ seconds per entity (50x slower) - Zero entities imported successfully - 100% of Workshop users unable to import files - No errors thrown - infinite wait - Forced immediate rollback to v5.6.3 ROOT CAUSE: v5.7.0 modified storage internal methods (getVerbsBySource_internal, getVerbsByTarget_internal) to use GraphAdjacencyIndex optimization, creating tight coupling where storage depends on index AND index depends on storage. This violated separation of concerns and created deadlock. SOLUTION (Architectural Fix): Reverted storage internals to v5.6.3 implementation (lines 2320-2444): - Storage layer simple, no index dependencies ✅ - GraphAdjacencyIndex can safely call storage.getVerbs() to rebuild ✅ - No circular dependency possible ✅ - Proper layered architecture restored ✅ LAYERS (Correct Architecture): Layer 3 (Brainy/Queries): CAN use GraphAdjacencyIndex Layer 2 (GraphAdjacencyIndex): Uses storage.getVerbs() to rebuild Layer 1 (Storage Internals): NO GraphAdjacencyIndex calls IMPACT: - Slightly slower GraphAdjacencyIndex.rebuild() (one-time init cost) - High-level queries still use optimized index - Import performance unaffected (writes don't trigger init) - NO breaking changes to public API TESTING: - Added 4 regression tests (tests/regression/v5.7.0-deadlock.test.ts) - All 1146 existing tests pass ✅ - Import + relationships complete in <1 second (not 760+) - No 12+ second delays per entity ✅ FILES CHANGED: - src/storage/baseStorage.ts (reverted lines 2320-2444 to v5.6.3) - tests/regression/v5.7.0-deadlock.test.ts (new regression tests) - CHANGELOG.md (comprehensive v5.7.1 entry with upgrade instructions) VERIFICATION: Workshop team should upgrade immediately: npm install @soulcraft/brainy@5.7.1 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
8be429870c
commit
eb9af45bab
3 changed files with 317 additions and 57 deletions
65
CHANGELOG.md
65
CHANGELOG.md
|
|
@ -2,8 +2,73 @@
|
|||
|
||||
All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
|
||||
|
||||
## [5.7.1](https://github.com/soulcraftlabs/brainy/compare/v5.7.0...v5.7.1) (2025-11-11)
|
||||
|
||||
### 🚨 CRITICAL BUG FIX
|
||||
|
||||
**v5.7.0 caused complete production failure - ALL imports hung indefinitely. This hotfix restores functionality.**
|
||||
|
||||
### Bug Description
|
||||
v5.7.0 introduced a circular dependency deadlock during GraphAdjacencyIndex initialization:
|
||||
- `GraphAdjacencyIndex.rebuild()` → `storage.getVerbs()`
|
||||
- `storage.getVerbsBySource_internal()` → `getGraphIndex()` (NEW in v5.7.0)
|
||||
- `getGraphIndex()` waiting for rebuild to complete
|
||||
- **DEADLOCK**: Each component waiting for the other
|
||||
|
||||
### Symptoms
|
||||
- ❌ ALL imports hung at "Reading Data Structure" stage for 760+ seconds
|
||||
- ❌ `brain.add()` operations took 12+ seconds per entity (50x slower than expected)
|
||||
- ❌ No errors thrown - infinite wait
|
||||
- ❌ Zero entities imported successfully
|
||||
- ❌ 100% of users unable to import files
|
||||
|
||||
### Root Cause
|
||||
v5.7.0 modified storage internal methods (`getVerbsBySource_internal`, `getVerbsByTarget_internal`) to use GraphAdjacencyIndex, creating tight coupling where:
|
||||
- Storage layer depends on index
|
||||
- Index depends on storage layer
|
||||
- Circular dependency = deadlock during initialization
|
||||
|
||||
### Fix (Architectural)
|
||||
Reverted storage internals to v5.6.3 implementation:
|
||||
- ✅ Storage layer is now simple and has no index dependencies
|
||||
- ✅ GraphAdjacencyIndex can safely call storage.getVerbs() to rebuild
|
||||
- ✅ No circular dependency possible
|
||||
- ✅ Proper separation of concerns restored
|
||||
|
||||
**Files changed**:
|
||||
- `src/storage/baseStorage.ts`: Reverted lines 2320-2444 to v5.6.3 implementation
|
||||
- `tests/regression/v5.7.0-deadlock.test.ts`: Added comprehensive regression tests
|
||||
|
||||
### Performance Impact
|
||||
- Slightly slower GraphAdjacencyIndex initialization (one-time cost during rebuild)
|
||||
- High-level query operations still use optimized index
|
||||
- Import performance unaffected (writes don't trigger index initialization)
|
||||
- **NO breaking changes to public API**
|
||||
|
||||
### Testing
|
||||
- ✅ 4 new regression tests verify no deadlock
|
||||
- ✅ All 1146 existing tests pass
|
||||
- ✅ Import + relationships complete in <1 second (not 760+ seconds)
|
||||
- ✅ No 12+ second delays per entity
|
||||
|
||||
### Verification
|
||||
Workshop team (production users) should upgrade immediately:
|
||||
```bash
|
||||
npm install @soulcraft/brainy@5.7.1
|
||||
```
|
||||
|
||||
Expected behavior after upgrade:
|
||||
- ✅ Imports work again
|
||||
- ✅ Fast entity creation (<100ms per entity)
|
||||
- ✅ No hangs or infinite waits
|
||||
- ✅ File operations responsive
|
||||
|
||||
---
|
||||
|
||||
### [5.7.0](https://github.com/soulcraftlabs/brainy/compare/v5.6.3...v5.7.0) (2025-11-11)
|
||||
|
||||
**⚠️ WARNING: This version has a critical deadlock bug. Use v5.7.1 instead.**
|
||||
|
||||
- test: skip flaky concurrent relationship test (race condition in duplicate detection) (a71785b)
|
||||
- perf: optimize imports with background deduplication (12-24x speedup) (02c80a0)
|
||||
|
||||
|
|
|
|||
|
|
@ -2320,90 +2320,126 @@ export abstract class BaseStorage extends BaseStorageAdapter {
|
|||
protected async getVerbsBySource_internal(
|
||||
sourceId: string
|
||||
): Promise<HNSWVerbWithMetadata[]> {
|
||||
// v5.7.0: BILLION-SCALE OPTIMIZATION - Use GraphAdjacencyIndex for O(log n) lookup
|
||||
// Previous: O(total_verbs) - scanned all 127 verb types
|
||||
// Now: O(log n) LSM-tree lookup + O(verbs_for_source) load
|
||||
// v5.7.1: Reverted to v5.6.3 implementation to fix circular dependency deadlock
|
||||
// v5.7.0 called getGraphIndex() here, creating deadlock during initialization:
|
||||
// GraphAdjacencyIndex.rebuild() → storage.getVerbs() → getVerbsBySource_internal() → getGraphIndex() → [deadlock]
|
||||
// v5.4.0: Type-first implementation - scan across all verb types
|
||||
// COW-aware: uses readWithInheritance for each verb
|
||||
await this.ensureInitialized()
|
||||
|
||||
const startTime = performance.now()
|
||||
|
||||
// Get GraphAdjacencyIndex (lazy-initialized)
|
||||
const graphIndex = await this.getGraphIndex()
|
||||
|
||||
// O(log n) lookup with bloom filter optimization
|
||||
const verbIds = await graphIndex.getVerbIdsBySource(sourceId)
|
||||
|
||||
// Load each verb by ID (uses existing optimized getVerb())
|
||||
const results: HNSWVerbWithMetadata[] = []
|
||||
for (const verbId of verbIds) {
|
||||
|
||||
// Iterate through all verb types
|
||||
for (let i = 0; i < VERB_TYPE_COUNT; i++) {
|
||||
const type = TypeUtils.getVerbFromIndex(i)
|
||||
const typeDir = `entities/verbs/${type}/vectors`
|
||||
|
||||
try {
|
||||
const verb = await this.getVerb(verbId)
|
||||
if (verb) {
|
||||
results.push(verb)
|
||||
// v5.4.0 FIX: List all verb files directly (not shard directories)
|
||||
// listObjectsInBranch returns full paths to .json files, not directories
|
||||
const verbFiles = await this.listObjectsInBranch(typeDir)
|
||||
|
||||
for (const verbPath of verbFiles) {
|
||||
// Skip if not a .json file
|
||||
if (!verbPath.endsWith('.json')) continue
|
||||
|
||||
try {
|
||||
const verb = await this.readWithInheritance(verbPath)
|
||||
if (verb && verb.sourceId === sourceId) {
|
||||
// v5.4.0: Use proper path helper instead of string replacement
|
||||
const metadataPath = getVerbMetadataPath(type, verb.id)
|
||||
const metadata = await this.readWithInheritance(metadataPath)
|
||||
|
||||
// v5.4.0: Extract standard fields from metadata to top-level (like nouns)
|
||||
results.push({
|
||||
...verb,
|
||||
weight: metadata?.weight,
|
||||
confidence: metadata?.confidence,
|
||||
createdAt: metadata?.createdAt
|
||||
? (typeof metadata.createdAt === 'number' ? metadata.createdAt : metadata.createdAt.seconds * 1000)
|
||||
: Date.now(),
|
||||
updatedAt: metadata?.updatedAt
|
||||
? (typeof metadata.updatedAt === 'number' ? metadata.updatedAt : metadata.updatedAt.seconds * 1000)
|
||||
: Date.now(),
|
||||
service: metadata?.service,
|
||||
createdBy: metadata?.createdBy,
|
||||
metadata: metadata || {} as VerbMetadata
|
||||
})
|
||||
}
|
||||
} catch (error) {
|
||||
// Skip verbs that fail to load
|
||||
}
|
||||
}
|
||||
} catch (error) {
|
||||
// Skip verbs that fail to load (handles deleted/corrupted verbs gracefully)
|
||||
// Skip types that have no data
|
||||
}
|
||||
}
|
||||
|
||||
const elapsed = performance.now() - startTime
|
||||
|
||||
// Performance monitoring - should be 100-10,000x faster than old O(n) scan
|
||||
if (elapsed > 50.0) {
|
||||
prodLog.warn(
|
||||
`getVerbsBySource_internal: Slow query for ${sourceId} ` +
|
||||
`(${verbIds.length} verbs, ${elapsed.toFixed(2)}ms). ` +
|
||||
`Expected <50ms with index optimization.`
|
||||
)
|
||||
}
|
||||
|
||||
return results
|
||||
}
|
||||
|
||||
/**
|
||||
* Get verbs by target (COW-aware implementation)
|
||||
* v5.7.0: BILLION-SCALE OPTIMIZATION - Use GraphAdjacencyIndex for O(log n) lookup
|
||||
* v5.7.1: Reverted to v5.6.3 implementation to fix circular dependency deadlock
|
||||
* v5.4.0: Fixed to directly list verb files instead of directories
|
||||
*/
|
||||
protected async getVerbsByTarget_internal(
|
||||
targetId: string
|
||||
): Promise<HNSWVerbWithMetadata[]> {
|
||||
// v5.7.0: BILLION-SCALE OPTIMIZATION - Use GraphAdjacencyIndex for O(log n) lookup
|
||||
// Previous: O(total_verbs) - scanned all 127 verb types
|
||||
// Now: O(log n) LSM-tree lookup + O(verbs_for_target) load
|
||||
// v5.7.1: Reverted to v5.6.3 implementation to fix circular dependency deadlock
|
||||
// v5.7.0 called getGraphIndex() here, creating deadlock during initialization
|
||||
// v5.4.0: Type-first implementation - scan across all verb types
|
||||
// COW-aware: uses readWithInheritance for each verb
|
||||
await this.ensureInitialized()
|
||||
|
||||
const startTime = performance.now()
|
||||
|
||||
// Get GraphAdjacencyIndex (lazy-initialized)
|
||||
const graphIndex = await this.getGraphIndex()
|
||||
|
||||
// O(log n) lookup with bloom filter optimization
|
||||
const verbIds = await graphIndex.getVerbIdsByTarget(targetId)
|
||||
|
||||
// Load each verb by ID (uses existing optimized getVerb())
|
||||
const results: HNSWVerbWithMetadata[] = []
|
||||
for (const verbId of verbIds) {
|
||||
|
||||
// Iterate through all verb types
|
||||
for (let i = 0; i < VERB_TYPE_COUNT; i++) {
|
||||
const type = TypeUtils.getVerbFromIndex(i)
|
||||
const typeDir = `entities/verbs/${type}/vectors`
|
||||
|
||||
try {
|
||||
const verb = await this.getVerb(verbId)
|
||||
if (verb) {
|
||||
results.push(verb)
|
||||
// v5.4.0 FIX: List all verb files directly (not shard directories)
|
||||
// listObjectsInBranch returns full paths to .json files, not directories
|
||||
const verbFiles = await this.listObjectsInBranch(typeDir)
|
||||
|
||||
for (const verbPath of verbFiles) {
|
||||
// Skip if not a .json file
|
||||
if (!verbPath.endsWith('.json')) continue
|
||||
|
||||
try {
|
||||
const verb = await this.readWithInheritance(verbPath)
|
||||
if (verb && verb.targetId === targetId) {
|
||||
// v5.4.0: Use proper path helper instead of string replacement
|
||||
const metadataPath = getVerbMetadataPath(type, verb.id)
|
||||
const metadata = await this.readWithInheritance(metadataPath)
|
||||
|
||||
// v5.4.0: Extract standard fields from metadata to top-level (like nouns)
|
||||
results.push({
|
||||
...verb,
|
||||
weight: metadata?.weight,
|
||||
confidence: metadata?.confidence,
|
||||
createdAt: metadata?.createdAt
|
||||
? (typeof metadata.createdAt === 'number' ? metadata.createdAt : metadata.createdAt.seconds * 1000)
|
||||
: Date.now(),
|
||||
updatedAt: metadata?.updatedAt
|
||||
? (typeof metadata.updatedAt === 'number' ? metadata.updatedAt : metadata.updatedAt.seconds * 1000)
|
||||
: Date.now(),
|
||||
service: metadata?.service,
|
||||
createdBy: metadata?.createdBy,
|
||||
metadata: metadata || {} as VerbMetadata
|
||||
})
|
||||
}
|
||||
} catch (error) {
|
||||
// Skip verbs that fail to load
|
||||
}
|
||||
}
|
||||
} catch (error) {
|
||||
// Skip verbs that fail to load (handles deleted/corrupted verbs gracefully)
|
||||
// Skip types that have no data
|
||||
}
|
||||
}
|
||||
|
||||
const elapsed = performance.now() - startTime
|
||||
|
||||
// Performance monitoring - should be 100-10,000x faster than old O(n) scan
|
||||
if (elapsed > 50.0) {
|
||||
prodLog.warn(
|
||||
`getVerbsByTarget_internal: Slow query for ${targetId} ` +
|
||||
`(${verbIds.length} verbs, ${elapsed.toFixed(2)}ms). ` +
|
||||
`Expected <50ms with index optimization.`
|
||||
)
|
||||
}
|
||||
|
||||
return results
|
||||
}
|
||||
|
||||
|
|
|
|||
159
tests/regression/v5.7.0-deadlock.test.ts
Normal file
159
tests/regression/v5.7.0-deadlock.test.ts
Normal file
|
|
@ -0,0 +1,159 @@
|
|||
import { describe, it, expect, beforeEach } from 'vitest'
|
||||
import { Brainy } from '../../src/brainy.js'
|
||||
import { VerbType } from '../../src/types/graphTypes.js'
|
||||
|
||||
/**
|
||||
* Regression test for v5.7.0 deadlock bug
|
||||
*
|
||||
* BUG DESCRIPTION:
|
||||
* v5.7.0 introduced a circular dependency deadlock during GraphAdjacencyIndex initialization:
|
||||
* - GraphAdjacencyIndex.rebuild() calls storage.getVerbs()
|
||||
* - storage.getVerbsBySource_internal() calls getGraphIndex()
|
||||
* - getGraphIndex() is waiting for rebuild() to complete
|
||||
* - DEADLOCK: Each waits for the other
|
||||
*
|
||||
* SYMPTOMS:
|
||||
* - ALL imports hang at "Reading Data Structure" stage
|
||||
* - brain.add() operations take 12+ seconds per entity (50x slower)
|
||||
* - No errors thrown - infinite wait
|
||||
* - Process continues (heartbeats) but makes no progress
|
||||
*
|
||||
* FIX (v5.7.1):
|
||||
* Reverted storage internals (getVerbsBySource_internal, getVerbsByTarget_internal)
|
||||
* to v5.6.3 implementation - no getGraphIndex() calls from storage layer.
|
||||
*
|
||||
* TEST STRATEGY:
|
||||
* 1. Create entities with relationships (triggers GraphAdjacencyIndex lazy init)
|
||||
* 2. Force rebuild by accessing graph operations
|
||||
* 3. Verify completes in <1 second (not 760+ seconds)
|
||||
*/
|
||||
describe('v5.7.0 Deadlock Regression', () => {
|
||||
let brain: Brainy
|
||||
|
||||
beforeEach(async () => {
|
||||
brain = new Brainy({ storage: { type: 'memory' } })
|
||||
await brain.init()
|
||||
})
|
||||
|
||||
it('should not deadlock during GraphAdjacencyIndex rebuild with existing verbs', async () => {
|
||||
// Create 10 entities
|
||||
const entities = []
|
||||
for (let i = 0; i < 10; i++) {
|
||||
const id = await brain.add({
|
||||
data: `Entity ${i}`,
|
||||
type: 'thing',
|
||||
metadata: { index: i }
|
||||
})
|
||||
entities.push(id)
|
||||
}
|
||||
|
||||
// Create relationships between them (triggers GraphAdjacencyIndex)
|
||||
for (let i = 0; i < 9; i++) {
|
||||
await brain.relate({
|
||||
from: entities[i],
|
||||
to: entities[i + 1],
|
||||
type: VerbType.RelatedTo
|
||||
})
|
||||
}
|
||||
|
||||
// This should complete in <1 second (not hang forever)
|
||||
const start = Date.now()
|
||||
|
||||
// Force GraphAdjacencyIndex usage by querying relationships
|
||||
const relations = await brain.getRelations({ from: entities[0] })
|
||||
|
||||
const elapsed = Date.now() - start
|
||||
|
||||
// Verify no deadlock
|
||||
expect(elapsed).toBeLessThan(1000)
|
||||
expect(relations.length).toBeGreaterThan(0)
|
||||
})
|
||||
|
||||
it('should handle imports without 12+ second delays per entity', async () => {
|
||||
// Simulate import workflow (like Workshop Excel import)
|
||||
const start = Date.now()
|
||||
|
||||
// Import 5 entities with relationships
|
||||
const importedEntities = []
|
||||
for (let i = 0; i < 5; i++) {
|
||||
const id = await brain.add({
|
||||
data: `Imported Entity ${i}`,
|
||||
type: 'person',
|
||||
metadata: {
|
||||
importId: 'test-import-001',
|
||||
sourceRow: i
|
||||
}
|
||||
})
|
||||
importedEntities.push(id)
|
||||
}
|
||||
|
||||
// Add relationships
|
||||
for (let i = 0; i < 4; i++) {
|
||||
await brain.relate({
|
||||
from: importedEntities[i],
|
||||
to: importedEntities[i + 1],
|
||||
type: VerbType.Knows
|
||||
})
|
||||
}
|
||||
|
||||
const elapsed = Date.now() - start
|
||||
|
||||
// In v5.7.0, this took 12+ seconds per entity (60+ seconds total)
|
||||
// In v5.7.1, should complete in <5 seconds for 5 entities
|
||||
expect(elapsed).toBeLessThan(5000)
|
||||
|
||||
// Verify all entities were created
|
||||
for (const id of importedEntities) {
|
||||
const entity = await brain.get(id)
|
||||
expect(entity).toBeDefined()
|
||||
}
|
||||
})
|
||||
|
||||
it('should allow GraphAdjacencyIndex rebuild without circular dependency', async () => {
|
||||
// Create initial data
|
||||
const entity1 = await brain.add({ data: 'Node A', type: 'thing' })
|
||||
const entity2 = await brain.add({ data: 'Node B', type: 'thing' })
|
||||
const entity3 = await brain.add({ data: 'Node C', type: 'thing' })
|
||||
|
||||
await brain.relate({ from: entity1, to: entity2, type: VerbType.RelatedTo })
|
||||
await brain.relate({ from: entity2, to: entity3, type: VerbType.RelatedTo })
|
||||
|
||||
// Accessing storage internals should not cause deadlock
|
||||
// GraphAdjacencyIndex initialization should complete successfully
|
||||
const start = Date.now()
|
||||
|
||||
// This would trigger initialization if not already done
|
||||
const relations = await brain.getRelations({ from: entity1 })
|
||||
|
||||
const elapsed = Date.now() - start
|
||||
|
||||
// Should be fast (no deadlock, no 12s delays)
|
||||
expect(elapsed).toBeLessThan(500)
|
||||
expect(relations).toHaveLength(1)
|
||||
expect(relations[0].to).toBe(entity2)
|
||||
})
|
||||
|
||||
it('should handle multiple concurrent adds without deadlock', async () => {
|
||||
// Simulate concurrent entity creation (like batch import)
|
||||
const start = Date.now()
|
||||
|
||||
const promises = []
|
||||
for (let i = 0; i < 10; i++) {
|
||||
promises.push(
|
||||
brain.add({
|
||||
data: `Concurrent Entity ${i}`,
|
||||
type: 'thing',
|
||||
metadata: { batch: true, index: i }
|
||||
})
|
||||
)
|
||||
}
|
||||
|
||||
const ids = await Promise.all(promises)
|
||||
const elapsed = Date.now() - start
|
||||
|
||||
// Should complete quickly (no 12s per entity delays)
|
||||
// 10 entities should take <2 seconds, not 120+ seconds
|
||||
expect(elapsed).toBeLessThan(2000)
|
||||
expect(ids).toHaveLength(10)
|
||||
})
|
||||
})
|
||||
Loading…
Add table
Add a link
Reference in a new issue