soulcraft/brainy
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases 335 Packages Wiki Activity Actions

feat(8.0)!: delete fork/branch/commit/history/versions — superseded by the Db API

Browse source 
The COW version-control surface (fork, branches, checkout, commit,
getHistory/streamHistory, asOfCommit, brain.versions) is gone, along with
its subsystems: src/versioning/, the COW object store (CommitLog,
CommitObject, RefManager, TreeObject), HistoricalStorageAdapter, and the
TypeAwareHNSWIndex path it kept alive. The Db API (now/transact/asOf/
with/persist/restore) is the one versioning model in 8.0.

Survivors and replacements:
- BlobStorage survives (the VFS stores file content through it), relocated
  to src/storage/blobStorage.ts with binaryDataCodec.ts; its adapter
  interface is now BlobStoreAdapter, slimmed to the consumed surface
  (write/read/has/delete/getMetadata + MIME-aware compression policy).
- brain.migrate() backup branches are replaced by persist-before-migrate:
  MigrateOptions.backupTo persists a hard-link snapshot of the current
  generation before any transform runs; MigrationResult.backupPath reports
  it, and brain.restore(path) brings it back wholesale.
- CLI: cow.ts (fork/branch/checkout/history/migrate) is replaced by
  snapshot.ts — snapshot <path>, restore <path>, history (tx-log),
  generation.
- New public read API: brain.transactionLog({limit}) exposes the reified
  tx-log (generation/timestamp/meta, newest first) that backs the CLI
  history command; TxLogEntry is exported.

Tests: superseded suites deleted; fork/commit blocks excised from shared
suites; BlobStorage tests relocated + reworked against the slimmed store;
migration tests now prove the backupTo snapshot/restore round trip; new
transactionLog coverage in db-mvcc.
This commit is contained in:
David Snelling 2026-06-10 15:22:47 -07:00
parent 431cd64406
commit 8f93add705
64 changed files with 1444 additions and 16313 deletions
Download patch file Download diff file Expand all files Collapse all files

30
tests/unit/storage/cow/BlobStorage.compression-policy.test.ts → tests/unit/storage/blobStorage.compression-policy.test.ts
View file

@ -2,7 +2,7 @@
* @module BlobStorage.compression-policy.test
* @description 2.5.0 #32 — content-type-aware compression policy.
*
* COW's BlobStorage now consults `BlobWriteOptions.mimeType` in `auto` mode
* BlobStorage consults `BlobWriteOptions.mimeType` in `auto` mode
* and skips zstd for MIME types known to be already heavily compressed (JPEG,
* PNG, MP4, MP3, ZIP, PDF, etc.). zstd over those formats is reliably a CPU
* loss for no measurable byte savings.
@ -24,11 +24,11 @@
import { describe, it, expect, beforeEach } from 'vitest'
import {
BlobStorage,
COWStorageAdapter,
BlobStoreAdapter,
isAlreadyCompressedMimeType
} from '../../../../src/storage/cow/BlobStorage.js'
} from '../../../src/storage/blobStorage.js'
class InMemoryCOWAdapter implements COWStorageAdapter {
class InMemoryBlobAdapter implements BlobStoreAdapter {
private store = new Map<string, Buffer>()
async get(key: string): Promise<Buffer | undefined> { return this.store.get(key) }
async put(key: string, data: Buffer): Promise<void> { this.store.set(key, data) }
@ -45,12 +45,12 @@ class InMemoryCOWAdapter implements COWStorageAdapter {
}
describe('BlobStorage compression policy (2.5.0 #32)', () => {
let adapter: InMemoryCOWAdapter
let adapter: InMemoryBlobAdapter
let blob: BlobStorage
beforeEach(() => {
adapter = new InMemoryCOWAdapter()
blob = new BlobStorage(adapter, { enableCompression: true })
adapter = new InMemoryBlobAdapter()
blob = new BlobStorage(adapter)
})
describe('isAlreadyCompressedMimeType helper', () => {
@ -90,7 +90,7 @@ describe('BlobStorage compression policy (2.5.0 #32)', () => {
it('skips compression for image/jpeg in auto mode (metadata records "none")', async () => {
const hash = await blob.write(HIGHLY_COMPRESSIBLE, {
compression: 'auto', type: 'blob', mimeType: 'image/jpeg'
compression: 'auto', mimeType: 'image/jpeg'
})
const meta = await blob.getMetadata(hash)
expect(meta?.compression).toBe('none')
@ -101,7 +101,7 @@ describe('BlobStorage compression policy (2.5.0 #32)', () => {
it('skips compression for video/mp4 in auto mode', async () => {
const hash = await blob.write(HIGHLY_COMPRESSIBLE, {
compression: 'auto', type: 'blob', mimeType: 'video/mp4'
compression: 'auto', mimeType: 'video/mp4'
})
const meta = await blob.getMetadata(hash)
expect(meta?.compression).toBe('none')
@ -109,7 +109,7 @@ describe('BlobStorage compression policy (2.5.0 #32)', () => {
it('skips compression for application/zip in auto mode', async () => {
const hash = await blob.write(HIGHLY_COMPRESSIBLE, {
compression: 'auto', type: 'blob', mimeType: 'application/zip'
compression: 'auto', mimeType: 'application/zip'
})
const meta = await blob.getMetadata(hash)
expect(meta?.compression).toBe('none')
@ -122,7 +122,7 @@ describe('BlobStorage compression policy (2.5.0 #32)', () => {
// falls back to 'none' — same outcome as a no-zstd install would see
// in production. Either way, the policy didn't block on text/plain.
const hash = await blob.write(HIGHLY_COMPRESSIBLE, {
compression: 'auto', type: 'blob', mimeType: 'text/plain'
compression: 'auto', mimeType: 'text/plain'
})
const meta = await blob.getMetadata(hash)
expect(meta?.compression === 'zstd' || meta?.compression === 'none').toBe(true)
@ -130,10 +130,10 @@ describe('BlobStorage compression policy (2.5.0 #32)', () => {
it('decompresses transparently on read regardless of compression decision', async () => {
const jpegHash = await blob.write(HIGHLY_COMPRESSIBLE, {
compression: 'auto', type: 'blob', mimeType: 'image/jpeg'
compression: 'auto', mimeType: 'image/jpeg'
})
const textHash = await blob.write(HIGHLY_COMPRESSIBLE, {
compression: 'auto', type: 'blob', mimeType: 'text/plain'
compression: 'auto', mimeType: 'text/plain'
})
// Different mime-type policies, same bytes back on read.
expect((await blob.read(jpegHash)).equals(HIGHLY_COMPRESSIBLE)).toBe(true)
@ -145,7 +145,7 @@ describe('BlobStorage compression policy (2.5.0 #32)', () => {
it('compression: "none" is honoured for text/plain (policy can\'t force compression on)', async () => {
const data = Buffer.alloc(4096, 0x43)
const hash = await blob.write(data, {
compression: 'none', type: 'blob', mimeType: 'text/plain'
compression: 'none', mimeType: 'text/plain'
})
const meta = await blob.getMetadata(hash)
expect(meta?.compression).toBe('none')
@ -156,7 +156,7 @@ describe('BlobStorage compression policy (2.5.0 #32)', () => {
it('compression: "zstd" is recorded as the intent for image/jpeg (policy applies only to auto)', async () => {
const data = Buffer.alloc(4096, 0x42)
const hash = await blob.write(data, {
compression: 'zstd', type: 'blob', mimeType: 'image/jpeg'
compression: 'zstd', mimeType: 'image/jpeg'
})
const meta = await blob.getMetadata(hash)
// Explicit zstd → the policy DOESN'T short-circuit; the metadata

392
tests/unit/storage/cow/BlobStorage.test.ts → tests/unit/storage/blobStorage.test.ts
View file

@ -1,25 +1,28 @@
/**
* Comprehensive tests for BlobStorage
* Comprehensive tests for BlobStorage (src/storage/blobStorage.ts)
*
* Tests:
* - Content-addressable storage (SHA-256)
* - Deduplication
* - Compression (zstd)
* - LRU caching
* - Batch operations
* - Reference counting
* - Garbage collection
* - Content-addressable storage (SHA-256, integrity verification)
* - Deduplication via reference counting
* - Compression (zstd, MIME-aware auto mode)
* - LRU caching (bounded cache still serves correct bytes)
* - Reference counting + delete-at-zero
* - Error handling
* - Performance characteristics
* - Wrapped-binary-data regressions (key-based dispatch)
*
* Cache-bypass pattern: the store has no cache-introspection API (the LRU is
* an internal optimization), so tests that must force a storage read create a
* FRESH BlobStorage over the same adapter — a cold cache by construction.
*/
import { describe, it, expect, beforeEach } from 'vitest'
import { BlobStorage, COWStorageAdapter } from '../../../../src/storage/cow/BlobStorage.js'
import { BlobStorage, BlobStoreAdapter } from '../../../src/storage/blobStorage.js'
/**
* Simple in-memory COW storage adapter for testing
* Simple in-memory blob store adapter for testing
*/
class InMemoryCOWAdapter implements COWStorageAdapter {
class InMemoryBlobAdapter implements BlobStoreAdapter {
private store = new Map<string, Buffer>()
async get(key: string): Promise<Buffer | undefined> {
@ -46,12 +49,12 @@ class InMemoryCOWAdapter implements COWStorageAdapter {
}
describe('BlobStorage', () => {
let adapter: COWStorageAdapter
let adapter: BlobStoreAdapter
let blobStorage: BlobStorage
beforeEach(() => {
adapter = new InMemoryCOWAdapter()
blobStorage = new BlobStorage(adapter, { enableCompression: true })
adapter = new InMemoryBlobAdapter()
blobStorage = new BlobStorage(adapter)
})
describe('Content-Addressable Storage', () => {
@ -84,14 +87,13 @@ describe('BlobStorage', () => {
const data = Buffer.from('test data')
const hash = await blobStorage.write(data)
// Clear cache so read() fetches from storage
blobStorage.clearCache()
// Corrupt the blob data
// Corrupt the blob data behind the store's back
await adapter.put(`blob:${hash}`, Buffer.from('corrupted'))
// Should detect corruption via hash verification
await expect(blobStorage.read(hash)).rejects.toThrow('integrity check failed')
// A fresh instance has a cold cache, so read() must hit storage and
// detect the corruption via hash verification.
const coldStore = new BlobStorage(adapter)
await expect(coldStore.read(hash)).rejects.toThrow('integrity check failed')
})
it('should check if blob exists', async () => {
@ -112,9 +114,9 @@ describe('BlobStorage', () => {
expect(hash1).toBe(hash2)
const stats = blobStorage.getStats()
expect(stats.totalBlobs).toBe(1)
expect(stats.dedupSavings).toBe(data.length)
// Exactly one stored blob + one metadata record
expect(await adapter.list('blob:')).toHaveLength(1)
expect(await adapter.list('blob-meta:')).toHaveLength(1)
})
it('should increment ref count on duplicate write', async () => {
@ -127,15 +129,17 @@ describe('BlobStorage', () => {
expect(metadata?.refCount).toBe(2)
})
it('should track deduplication savings', async () => {
it('should track every duplicate write in the reference count', async () => {
const data = Buffer.from('x'.repeat(1000))
const hash1 = await blobStorage.write(data)
const hash2 = await blobStorage.write(data)
const hash3 = await blobStorage.write(data)
const stats = blobStorage.getStats()
expect(stats.dedupSavings).toBe(2000) // 2 duplicates × 1000 bytes
expect(hash2).toBe(hash1)
expect(hash3).toBe(hash1)
const metadata = await blobStorage.getMetadata(hash1)
expect(metadata?.refCount).toBe(3)
})
})
@ -143,15 +147,12 @@ describe('BlobStorage', () => {
it('should compress large text data with zstd', async () => {
const data = Buffer.from('a'.repeat(10000))
const hash = await blobStorage.write(data, {
type: 'metadata',
compression: 'zstd'
})
const hash = await blobStorage.write(data, { compression: 'zstd' })
const metadata = await blobStorage.getMetadata(hash)
// zstd may not be available in test environment - falls back to 'none'
// This is expected behavior (see BlobStorage initCompression fallback)
// This is expected behavior (see BlobStorage.ensureCompressionReady fallback)
if (metadata?.compression === 'zstd') {
expect(metadata.compressedSize).toBeLessThan(metadata.size)
} else {
@ -163,10 +164,7 @@ describe('BlobStorage', () => {
it('should decompress zstd data on read', async () => {
const originalData = Buffer.from('test data '.repeat(100))
const hash = await blobStorage.write(originalData, {
type: 'metadata',
compression: 'zstd'
})
const hash = await blobStorage.write(originalData, { compression: 'zstd' })
const retrieved = await blobStorage.read(hash)
@ -176,36 +174,30 @@ describe('BlobStorage', () => {
it('should not compress small blobs', async () => {
const data = Buffer.from('small')
const hash = await blobStorage.write(data, {
compression: 'auto'
})
const hash = await blobStorage.write(data, { compression: 'auto' })
const metadata = await blobStorage.getMetadata(hash)
expect(metadata?.compression).toBe('none')
})
it('should not compress vector data (already dense)', async () => {
const vectorData = Buffer.from(new Float32Array([1, 2, 3, 4, 5]))
const hash = await blobStorage.write(vectorData, {
type: 'vector',
compression: 'auto'
})
const metadata = await blobStorage.getMetadata(hash)
expect(metadata?.compression).toBe('none')
})
it('should auto-compress metadata/tree/commit types', async () => {
it('should skip compression for already-compressed MIME types in auto mode', async () => {
const data = Buffer.from('x'.repeat(5000))
const hash = await blobStorage.write(data, {
type: 'metadata',
compression: 'auto'
compression: 'auto',
mimeType: 'image/jpeg'
})
const metadata = await blobStorage.getMetadata(hash)
expect(metadata?.compression).toBe('none')
})
it('should auto-compress large compressible payloads', async () => {
const data = Buffer.from('x'.repeat(5000))
const hash = await blobStorage.write(data, { compression: 'auto' })
const metadata = await blobStorage.getMetadata(hash)
// Should compress if zstd is available
@ -216,91 +208,37 @@ describe('BlobStorage', () => {
})
describe('LRU Caching', () => {
it('should cache blob on read', async () => {
it('should serve identical bytes from cache and from storage', async () => {
const data = Buffer.from('cached data')
const hash = await blobStorage.write(data)
// First read (cache miss)
await blobStorage.read(hash)
// Warm read (write-through cache) and cold read (fresh instance)
const warm = await blobStorage.read(hash)
const cold = await new BlobStorage(adapter).read(hash)
// Second read (cache hit)
await blobStorage.read(hash)
const stats = blobStorage.getStats()
expect(stats.cacheHits).toBeGreaterThan(0)
expect(warm.equals(data)).toBe(true)
expect(cold.equals(data)).toBe(true)
})
it('should evict LRU entries when cache is full', async () => {
const smallCache = new BlobStorage(adapter, {
cacheMaxSize: 100, // Very small cache
enableCompression: false
})
it('should keep serving correct bytes when the cache evicts under pressure', async () => {
const smallCache = new BlobStorage(adapter, { cacheMaxSize: 100 })
// Write blobs that exceed cache size
const blob1 = Buffer.from('x'.repeat(50))
const blob2 = Buffer.from('y'.repeat(50))
const blob3 = Buffer.from('z'.repeat(50))
const hash1 = await smallCache.write(blob1)
const hash2 = await smallCache.write(blob2)
const hash3 = await smallCache.write(blob3) // Should evict hash1
// Read all blobs
await smallCache.read(hash1)
await smallCache.read(hash2)
await smallCache.read(hash3)
// hash1 should have been evicted, causing cache miss
const stats = smallCache.getStats()
expect(stats.cacheMisses).toBeGreaterThan(0)
})
it('should clear cache on demand', async () => {
const data = Buffer.from('test')
const hash = await blobStorage.write(data)
await blobStorage.read(hash) // Cache it
blobStorage.clearCache()
await blobStorage.read(hash) // Should be cache miss
const stats = blobStorage.getStats()
expect(stats.cacheMisses).toBeGreaterThan(0)
})
})
describe('Batch Operations', () => {
it('should write multiple blobs in parallel', async () => {
const blobs: Array<[Buffer, any]> = [
[Buffer.from('blob1'), undefined],
[Buffer.from('blob2'), undefined],
[Buffer.from('blob3'), undefined]
// Write blobs that exceed cache size (forces LRU eviction)
const blobs = [
Buffer.from('x'.repeat(50)),
Buffer.from('y'.repeat(50)),
Buffer.from('z'.repeat(50))
]
const hashes: string[] = []
for (const blob of blobs) {
hashes.push(await smallCache.write(blob))
}
const hashes = await blobStorage.writeBatch(blobs)
expect(hashes).toHaveLength(3)
expect(hashes[0]).toHaveLength(64)
expect(hashes[1]).toHaveLength(64)
expect(hashes[2]).toHaveLength(64)
})
it('should read multiple blobs in parallel', async () => {
const data1 = Buffer.from('blob1')
const data2 = Buffer.from('blob2')
const data3 = Buffer.from('blob3')
const hash1 = await blobStorage.write(data1)
const hash2 = await blobStorage.write(data2)
const hash3 = await blobStorage.write(data3)
const blobs = await blobStorage.readBatch([hash1, hash2, hash3])
expect(blobs).toHaveLength(3)
expect(blobs[0].toString()).toBe('blob1')
expect(blobs[1].toString()).toBe('blob2')
expect(blobs[2].toString()).toBe('blob3')
// Every blob still reads back correctly, evicted or not
for (let i = 0; i < blobs.length; i++) {
const retrieved = await smallCache.read(hashes[i])
expect(retrieved.equals(blobs[i])).toBe(true)
}
})
})
@ -339,120 +277,28 @@ describe('BlobStorage', () => {
})
})
describe('Garbage Collection', () => {
it('should delete unreferenced blobs', async () => {
const blob1 = Buffer.from('referenced')
const blob2 = Buffer.from('unreferenced')
const hash1 = await blobStorage.write(blob1)
const hash2 = await blobStorage.write(blob2)
// Manually set refCount to 0 for unreferenced blob
// (In real COW usage, refCount tracks actual references from commits/trees)
// GC only deletes when refCount === 0 AND not in referenced set
const metadata2 = await blobStorage.getMetadata(hash2)
if (metadata2) {
metadata2.refCount = 0
await adapter.put(`blob-meta:${hash2}`, Buffer.from(JSON.stringify(metadata2)))
}
// Mark only hash1 as referenced
const referenced = new Set([hash1])
const deleted = await blobStorage.garbageCollect(referenced)
expect(deleted).toBeGreaterThan(0)
expect(await blobStorage.has(hash1)).toBe(true)
expect(await blobStorage.has(hash2)).toBe(false)
})
it('should not delete referenced blobs', async () => {
const blob1 = Buffer.from('ref1')
const blob2 = Buffer.from('ref2')
const hash1 = await blobStorage.write(blob1)
const hash2 = await blobStorage.write(blob2)
// Both referenced
const referenced = new Set([hash1, hash2])
const deleted = await blobStorage.garbageCollect(referenced)
expect(deleted).toBe(0)
expect(await blobStorage.has(hash1)).toBe(true)
expect(await blobStorage.has(hash2)).toBe(true)
})
})
describe('Metadata', () => {
it('should store blob metadata', async () => {
const data = Buffer.from('test')
const hash = await blobStorage.write(data, {
type: 'metadata',
compression: 'none'
})
const hash = await blobStorage.write(data, { compression: 'none' })
const metadata = await blobStorage.getMetadata(hash)
expect(metadata?.hash).toBe(hash)
expect(metadata?.size).toBe(data.length)
expect(metadata?.type).toBe('metadata')
expect(metadata?.compression).toBe('none')
expect(metadata?.createdAt).toBeGreaterThan(0)
expect(metadata?.refCount).toBe(1)
})
})
describe('List Operations', () => {
it('should list all blobs', async () => {
const hash1 = await blobStorage.write(Buffer.from('blob1'))
const hash2 = await blobStorage.write(Buffer.from('blob2'))
const hash3 = await blobStorage.write(Buffer.from('blob3'))
const blobs = await blobStorage.listBlobs()
expect(blobs).toContain(hash1)
expect(blobs).toContain(hash2)
expect(blobs).toContain(hash3)
})
})
describe('Statistics', () => {
it('should track storage statistics', async () => {
const data1 = Buffer.from('x'.repeat(1000))
const data2 = Buffer.from('y'.repeat(2000))
await blobStorage.write(data1)
await blobStorage.write(data2)
const stats = blobStorage.getStats()
expect(stats.totalBlobs).toBe(2)
expect(stats.totalSize).toBe(3000)
expect(stats.avgBlobSize).toBe(1500)
})
it('should calculate compression ratio', async () => {
const data = Buffer.from('a'.repeat(10000))
await blobStorage.write(data, {
type: 'metadata',
compression: 'zstd'
})
const stats = blobStorage.getStats()
// Compression ratio should be > 1 if compressed
if (stats.compressedSize < stats.totalSize) {
expect(stats.compressionRatio).toBeGreaterThan(1)
}
it('should return undefined metadata for unknown hashes', async () => {
expect(await blobStorage.getMetadata('f'.repeat(64))).toBeUndefined()
})
})
describe('Error Handling', () => {
it('should throw on reading non-existent blob', async () => {
// Use 'f' instead of '0' to avoid NULL_HASH sentinel value
await expect(
blobStorage.read('f'.repeat(64))
).rejects.toThrow('Blob metadata not found')
@ -462,14 +308,12 @@ describe('BlobStorage', () => {
const data = Buffer.from('test')
const hash = await blobStorage.write(data)
// Clear cache so read() actually checks metadata
blobStorage.clearCache()
// Delete metadata but keep blob
// Delete metadata but keep blob bytes
await adapter.delete(`blob-meta:${hash}`)
// Use skipCache to ensure we check metadata
await expect(blobStorage.read(hash, { skipCache: true })).rejects.toThrow('metadata not found')
// A fresh instance has a cold cache, so read() must consult metadata
const coldStore = new BlobStorage(adapter)
await expect(coldStore.read(hash)).rejects.toThrow('metadata not found')
})
})
@ -510,10 +354,10 @@ describe('BlobStorage', () => {
})
})
describe('v5.10.0 Regression - Blob Integrity with Wrapped Data', () => {
it('should handle wrapped binary data without hash mismatch (v5.10.0 fix)', async () => {
describe('Wrapped-binary regression (v5.10.0) - hash verification on unwrapped bytes', () => {
it('should handle wrapped binary data without hash mismatch', async () => {
// Import TestWrappingAdapter that actually wraps data like production
const { TestWrappingAdapter } = await import('../../../helpers/TestWrappingAdapter.js')
const { TestWrappingAdapter } = await import('../../helpers/TestWrappingAdapter.js')
const wrappingAdapter = new TestWrappingAdapter()
const testBlobStorage = new BlobStorage(wrappingAdapter)
@ -522,20 +366,17 @@ describe('BlobStorage', () => {
// Write blob (TestWrappingAdapter wraps as {_binary: true, data: "base64..."})
const hash = await testBlobStorage.write(originalData)
// Clear cache to force re-read from storage (bypasses in-memory cache)
testBlobStorage.clearCache()
// v5.10.0 bug: This would fail with "Blob integrity check failed"
// because BlobStorage.read() was hashing the wrapped data instead of unwrapped
// v5.10.1 fix: unwrapBinaryData() is called before hash verification
const retrieved = await testBlobStorage.read(hash)
// Fresh instance = cold cache: read() must fetch + unwrap from storage.
// v5.10.0 bug: read() hashed the wrapped bytes instead of the unwrapped
// content; the fix runs unwrapBinaryData() before hash verification.
const retrieved = await new BlobStorage(wrappingAdapter).read(hash)
expect(retrieved.equals(originalData)).toBe(true)
expect(retrieved.toString()).toBe('test content for v5.10.0 regression test')
})
it('should handle multiple wrapped blobs without integrity errors', async () => {
const { TestWrappingAdapter } = await import('../../../helpers/TestWrappingAdapter.js')
const { TestWrappingAdapter } = await import('../../helpers/TestWrappingAdapter.js')
const wrappingAdapter = new TestWrappingAdapter()
const testBlobStorage = new BlobStorage(wrappingAdapter)
@ -554,19 +395,17 @@ describe('BlobStorage', () => {
hashes.push(hash)
}
// Clear cache
testBlobStorage.clearCache()
// Read all blobs (would fail in v5.10.0)
// Cold-cache instance forces storage reads
const coldStore = new BlobStorage(wrappingAdapter)
for (let i = 0; i < hashes.length; i++) {
const retrieved = await testBlobStorage.read(hashes[i])
const retrieved = await coldStore.read(hashes[i])
expect(retrieved.equals(testData[i])).toBe(true)
}
})
it('should work even if adapter fails to unwrap (defense-in-depth)', async () => {
// Create a buggy adapter that doesn't unwrap properly
class BuggyAdapter implements COWStorageAdapter {
class BuggyAdapter implements BlobStoreAdapter {
private storage = new Map<string, any>()
async get(key: string): Promise<any | undefined> {
@ -601,21 +440,20 @@ describe('BlobStorage', () => {
const originalData = Buffer.from('test defense-in-depth')
const hash = await testBlobStorage.write(originalData)
testBlobStorage.clearCache()
// Even with buggy adapter, BlobStorage.read() should unwrap and verify correctly
const retrieved = await testBlobStorage.read(hash)
// Even with buggy adapter (and a cold cache), read() should unwrap and
// verify correctly
const retrieved = await new BlobStorage(buggyAdapter).read(hash)
expect(retrieved.equals(originalData)).toBe(true)
})
})
describe('v6.2.0 Regression - Key-Based Dispatch (Permanent Fix)', () => {
describe('Key-based dispatch regression (v6.2.0)', () => {
it('should handle JSON-like compressed data without integrity failures', async () => {
// THE KILLER TEST CASE: Data that looks like JSON when compressed
// This would fail with v5.10.1 wrapBinaryData() guessing approach
const { TestWrappingAdapter } = await import('../../../helpers/TestWrappingAdapter.js')
const { TestWrappingAdapter } = await import('../../helpers/TestWrappingAdapter.js')
const wrappingAdapter = new TestWrappingAdapter()
const testBlobStorage = new BlobStorage(wrappingAdapter, { enableCompression: true })
const testBlobStorage = new BlobStorage(wrappingAdapter)
// Create JSON data that will be compressed
const jsonData = { nested: { key: 'value', array: [1, 2, 3] }, repeated: 'x'.repeat(1000) }
@ -624,54 +462,23 @@ describe('BlobStorage', () => {
// Write blob (compression happens, might create JSON-parseable bytes)
const hash = await testBlobStorage.write(originalData)
// Clear cache to force re-read from storage
testBlobStorage.clearCache()
// v5.10.1 bug: If compressed bytes accidentally parse as JSON,
// wrapBinaryData() would store parsed object instead of wrapped binary
// On read: JSON.stringify(object) !== original compressed bytes → hash mismatch
//
// v6.2.0 fix: Key-based dispatch eliminates guessing
// 'blob:hash' → Always wrapped as binary, never parsed
const retrieved = await testBlobStorage.read(hash)
const retrieved = await new BlobStorage(wrappingAdapter).read(hash)
// Hash MUST match
expect(BlobStorage.hash(retrieved)).toBe(hash)
expect(retrieved.equals(originalData)).toBe(true)
})
it('should correctly dispatch all key types', async () => {
// Verify key-based dispatch works for all COW key patterns
const { TestWrappingAdapter } = await import('../../../helpers/TestWrappingAdapter.js')
const wrappingAdapter = new TestWrappingAdapter()
const testBlobStorage = new BlobStorage(wrappingAdapter)
// Test binary blob keys
const blobData = Buffer.from('binary blob content')
const blobHash = await testBlobStorage.write(blobData, { type: 'blob' })
testBlobStorage.clearCache()
const retrievedBlob = await testBlobStorage.read(blobHash)
expect(retrievedBlob.equals(blobData)).toBe(true)
// Test commit keys
const commitData = Buffer.from('commit content')
const commitHash = await testBlobStorage.write(commitData, { type: 'commit' })
testBlobStorage.clearCache()
const retrievedCommit = await testBlobStorage.read(commitHash)
expect(retrievedCommit.equals(commitData)).toBe(true)
// Test tree keys
const treeData = Buffer.from('tree content')
const treeHash = await testBlobStorage.write(treeData, { type: 'tree' })
testBlobStorage.clearCache()
const retrievedTree = await testBlobStorage.read(treeHash)
expect(retrievedTree.equals(treeData)).toBe(true)
})
it('should handle metadata keys correctly', async () => {
// Verify that key-based dispatch correctly handles metadata keys
// This test verifies the dispatch logic, not the full read/write cycle
const { TestWrappingAdapter } = await import('../../../helpers/TestWrappingAdapter.js')
const { TestWrappingAdapter } = await import('../../helpers/TestWrappingAdapter.js')
const wrappingAdapter = new TestWrappingAdapter()
// Test metadata key dispatch: should parse as JSON
@ -688,10 +495,10 @@ describe('BlobStorage', () => {
expect(retrieved.size).toBe(42)
})
it('should never call wrapBinaryData on write path', async () => {
// Verify that baseStorage COW adapter uses key-based dispatch,
it('should never parse blob bytes as JSON on the write path', async () => {
// Verify that the blob bridge uses key-based dispatch,
// NOT wrapBinaryData() guessing
const { TestWrappingAdapter } = await import('../../../helpers/TestWrappingAdapter.js')
const { TestWrappingAdapter } = await import('../../helpers/TestWrappingAdapter.js')
const wrappingAdapter = new TestWrappingAdapter()
const testBlobStorage = new BlobStorage(wrappingAdapter)
@ -699,8 +506,7 @@ describe('BlobStorage', () => {
const problematicData = Buffer.from('[{"looks":"like","valid":"json"}]')
const hash = await testBlobStorage.write(problematicData)
testBlobStorage.clearCache()
const retrieved = await testBlobStorage.read(hash)
const retrieved = await new BlobStorage(wrappingAdapter).read(hash)
// Should retrieve exact same bytes (no JSON parsing occurred)
expect(retrieved.equals(problematicData)).toBe(true)

538
tests/unit/versioning/VersionDiff.test.ts
View file

@ -1,538 +0,0 @@
/**
* VersionDiff Unit Tests (v5.3.0)
*
* Tests deep object comparison:
* - Added fields
* - Removed fields
* - Modified fields
* - Type changes
* - Nested object comparison
* - Array comparison
*/
import { describe, it, expect } from 'vitest'
import { compareEntityVersions } from '../../../src/versioning/VersionDiff.js'
import type { NounMetadata } from '../../../src/coreTypes.js'
describe('VersionDiff', () => {
describe('compareEntityVersions()', () => {
it('should detect added fields', () => {
const from: NounMetadata = {
id: 'user-1',
type: 'user',
name: 'Alice',
metadata: { email: 'alice@example.com' }
}
const to: NounMetadata = {
id: 'user-1',
type: 'user',
name: 'Alice',
metadata: {
email: 'alice@example.com',
city: 'NYC',
age: 30
}
}
const diff = compareEntityVersions(from, to, {
entityId: 'user-1',
fromVersion: 1,
toVersion: 2
})
expect(diff.added.length).toBe(2)
expect(diff.added.some(c => c.path.includes('city'))).toBe(true)
expect(diff.added.some(c => c.path.includes('age'))).toBe(true)
expect(diff.added.find(c => c.path.includes('city'))?.newValue).toBe('NYC')
})
it('should detect removed fields', () => {
const from: NounMetadata = {
id: 'user-1',
type: 'user',
name: 'Alice',
metadata: {
email: 'alice@example.com',
city: 'NYC',
age: 30
}
}
const to: NounMetadata = {
id: 'user-1',
type: 'user',
name: 'Alice',
metadata: { email: 'alice@example.com' }
}
const diff = compareEntityVersions(from, to, {
entityId: 'user-1',
fromVersion: 1,
toVersion: 2
})
expect(diff.removed.length).toBe(2)
expect(diff.removed.some(c => c.path.includes('city'))).toBe(true)
expect(diff.removed.some(c => c.path.includes('age'))).toBe(true)
expect(diff.removed.find(c => c.path.includes('city'))?.oldValue).toBe('NYC')
})
it('should detect modified fields', () => {
const from: NounMetadata = {
id: 'user-1',
type: 'user',
name: 'Alice',
metadata: {
email: 'alice@example.com',
status: 'active'
}
}
const to: NounMetadata = {
id: 'user-1',
type: 'user',
name: 'Alice Smith',
metadata: {
email: 'alice.smith@example.com',
status: 'active'
}
}
const diff = compareEntityVersions(from, to, {
entityId: 'user-1',
fromVersion: 1,
toVersion: 2
})
expect(diff.modified.length).toBe(2)
const nameChange = diff.modified.find(c => c.path.includes('name'))
expect(nameChange?.oldValue).toBe('Alice')
expect(nameChange?.newValue).toBe('Alice Smith')
const emailChange = diff.modified.find(c => c.path.includes('email'))
expect(emailChange?.oldValue).toBe('alice@example.com')
expect(emailChange?.newValue).toBe('alice.smith@example.com')
})
it('should detect type changes', () => {
const from: NounMetadata = {
id: 'config-1',
type: 'thing',
name: 'Config',
metadata: { value: '100' }
}
const to: NounMetadata = {
id: 'config-1',
type: 'thing',
name: 'Config',
metadata: { value: 100 }
}
const diff = compareEntityVersions(from, to, {
entityId: 'config-1',
fromVersion: 1,
toVersion: 2
})
expect(diff.typeChanged.length).toBe(1)
const typeChange = diff.typeChanged[0]
expect(typeChange.path).toContain('value')
expect(typeChange.oldType).toBe('string')
expect(typeChange.newType).toBe('number')
expect(typeChange.oldValue).toBe('100')
expect(typeChange.newValue).toBe(100)
})
it('should detect identical versions', () => {
const entity: NounMetadata = {
id: 'doc-1',
type: 'document',
name: 'Doc',
metadata: { content: 'Unchanged' }
}
const diff = compareEntityVersions(entity, entity, {
entityId: 'doc-1',
fromVersion: 1,
toVersion: 2
})
expect(diff.identical).toBe(true)
expect(diff.totalChanges).toBe(0)
expect(diff.added).toHaveLength(0)
expect(diff.removed).toHaveLength(0)
expect(diff.modified).toHaveLength(0)
})
it('should handle nested object changes', () => {
const from: NounMetadata = {
id: 'user-1',
type: 'user',
name: 'Alice',
metadata: {
address: {
street: '123 Main St',
city: 'NYC'
}
}
}
const to: NounMetadata = {
id: 'user-1',
type: 'user',
name: 'Alice',
metadata: {
address: {
street: '456 Oak Ave',
city: 'NYC',
zip: '10001'
}
}
}
const diff = compareEntityVersions(from, to, {
entityId: 'user-1',
fromVersion: 1,
toVersion: 2
})
expect(diff.modified.some(c => c.path.includes('address.street'))).toBe(true)
expect(diff.added.some(c => c.path.includes('address.zip'))).toBe(true)
const streetChange = diff.modified.find(c => c.path.includes('address.street'))
expect(streetChange?.oldValue).toBe('123 Main St')
expect(streetChange?.newValue).toBe('456 Oak Ave')
})
it('should handle array changes', () => {
const from: NounMetadata = {
id: 'doc-1',
type: 'document',
name: 'Doc',
metadata: {
tags: ['a', 'b', 'c']
}
}
const to: NounMetadata = {
id: 'doc-1',
type: 'document',
name: 'Doc',
metadata: {
tags: ['a', 'b', 'd']
}
}
const diff = compareEntityVersions(from, to, {
entityId: 'doc-1',
fromVersion: 1,
toVersion: 2
})
// Array element change detected as modification
expect(diff.totalChanges).toBeGreaterThan(0)
})
it('should handle null and undefined', () => {
const from: NounMetadata = {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: {
a: null,
b: undefined,
c: 'value'
}
}
const to: NounMetadata = {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: {
a: 'now-value',
b: null,
c: 'value'
}
}
const diff = compareEntityVersions(from, to, {
entityId: 'test-1',
fromVersion: 1,
toVersion: 2
})
expect(diff.totalChanges).toBeGreaterThan(0)
})
it('should ignore specified fields', () => {
const from: NounMetadata = {
id: 'user-1',
type: 'user',
name: 'Alice',
metadata: {
email: 'alice@example.com',
lastModified: 1000,
internal: 'ignore-me'
}
}
const to: NounMetadata = {
id: 'user-1',
type: 'user',
name: 'Alice Smith',
metadata: {
email: 'alice@example.com',
lastModified: 2000,
internal: 'changed'
}
}
const diff = compareEntityVersions(from, to, {
entityId: 'user-1',
fromVersion: 1,
toVersion: 2,
ignoreFields: ['lastModified', 'internal']
})
// Should only detect name change
expect(diff.totalChanges).toBe(1)
expect(diff.modified.some(c => c.path.includes('name'))).toBe(true)
expect(diff.modified.some(c => c.path.includes('lastModified'))).toBe(false)
expect(diff.modified.some(c => c.path.includes('internal'))).toBe(false)
})
it('should respect maxDepth option', () => {
const from: NounMetadata = {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: {
level1: {
level2: {
level3: {
level4: 'deep-value'
}
}
}
}
}
const to: NounMetadata = {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: {
level1: {
level2: {
level3: {
level4: 'changed-value'
}
}
}
}
}
const diff = compareEntityVersions(from, to, {
entityId: 'test-1',
fromVersion: 1,
toVersion: 2,
maxDepth: 2 // Stop at level2
})
// Should detect change at metadata.level1.level2 level
expect(diff.totalChanges).toBeGreaterThan(0)
})
it('should handle empty objects', () => {
const from: NounMetadata = {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: {}
}
const to: NounMetadata = {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: { value: 123 }
}
const diff = compareEntityVersions(from, to, {
entityId: 'test-1',
fromVersion: 1,
toVersion: 2
})
expect(diff.added.length).toBe(1)
expect(diff.added[0].newValue).toBe(123)
})
it('should calculate total changes correctly', () => {
const from: NounMetadata = {
id: 'user-1',
type: 'user',
name: 'Alice',
metadata: {
email: 'alice@example.com',
status: 'active',
age: 30
}
}
const to: NounMetadata = {
id: 'user-1',
type: 'user',
name: 'Alice Smith',
metadata: {
email: 'alice.smith@example.com',
city: 'NYC'
}
}
const diff = compareEntityVersions(from, to, {
entityId: 'user-1',
fromVersion: 1,
toVersion: 2
})
const expectedTotal =
diff.added.length +
diff.removed.length +
diff.modified.length +
diff.typeChanged.length
expect(diff.totalChanges).toBe(expectedTotal)
})
it('should handle complex real-world changes', () => {
const from: NounMetadata = {
id: 'project-1',
type: 'thing',
name: 'My Project',
metadata: {
description: 'Old description',
status: 'draft',
team: ['alice', 'bob'],
config: {
theme: 'light',
notifications: true
},
createdAt: 1000
}
}
const to: NounMetadata = {
id: 'project-1',
type: 'thing',
name: 'My Awesome Project',
metadata: {
description: 'New description',
status: 'active',
team: ['alice', 'bob', 'charlie'],
config: {
theme: 'dark',
notifications: true,
language: 'en'
},
createdAt: 1000,
updatedAt: 2000
}
}
const diff = compareEntityVersions(from, to, {
entityId: 'project-1',
fromVersion: 1,
toVersion: 2
})
expect(diff.totalChanges).toBeGreaterThan(0)
expect(diff.modified.length).toBeGreaterThan(0)
expect(diff.added.length).toBeGreaterThan(0)
const nameChange = diff.modified.find(c => c.path.includes('name'))
expect(nameChange?.newValue).toBe('My Awesome Project')
})
it('should handle boolean changes', () => {
const from: NounMetadata = {
id: 'feature-1',
type: 'thing',
name: 'Feature',
metadata: { enabled: false }
}
const to: NounMetadata = {
id: 'feature-1',
type: 'thing',
name: 'Feature',
metadata: { enabled: true }
}
const diff = compareEntityVersions(from, to, {
entityId: 'feature-1',
fromVersion: 1,
toVersion: 2
})
expect(diff.modified.length).toBe(1)
expect(diff.modified[0].oldValue).toBe(false)
expect(diff.modified[0].newValue).toBe(true)
})
it('should handle number changes', () => {
const from: NounMetadata = {
id: 'counter-1',
type: 'thing',
name: 'Counter',
metadata: { count: 10 }
}
const to: NounMetadata = {
id: 'counter-1',
type: 'thing',
name: 'Counter',
metadata: { count: 20 }
}
const diff = compareEntityVersions(from, to, {
entityId: 'counter-1',
fromVersion: 1,
toVersion: 2
})
expect(diff.modified.length).toBe(1)
expect(diff.modified[0].oldValue).toBe(10)
expect(diff.modified[0].newValue).toBe(20)
})
it('should handle date/timestamp changes', () => {
const from: NounMetadata = {
id: 'event-1',
type: 'thing',
name: 'Event',
metadata: { timestamp: 1000 }
}
const to: NounMetadata = {
id: 'event-1',
type: 'thing',
name: 'Event',
metadata: { timestamp: 2000 }
}
const diff = compareEntityVersions(from, to, {
entityId: 'event-1',
fromVersion: 1,
toVersion: 2
})
expect(diff.modified.length).toBe(1)
expect(diff.modified[0].path).toContain('timestamp')
})
})
})

710
tests/unit/versioning/VersionManager.test.ts
View file

@ -1,710 +0,0 @@
/**
* VersionManager Unit Tests (v5.3.0)
*
* Tests the core versioning engine in isolation:
* - Save versions
* - Restore versions
* - List versions
* - Compare versions
* - Prune versions
* - Content deduplication
* - Branch awareness
*/
import { describe, it, expect, beforeEach, vi } from 'vitest'
import { VersionManager } from '../../../src/versioning/VersionManager.js'
import type { NounMetadata } from '../../../src/coreTypes.js'
describe('VersionManager', () => {
let manager: VersionManager
let mockBrain: any
let mockStorage: Map<string, any>
let mockIndex: Map<string, any>
beforeEach(() => {
// Mock storage
mockStorage = new Map()
mockIndex = new Map()
// Mock Brainy instance
mockBrain = {
currentBranch: 'main',
storageAdapter: {
// v6.3.0: VersionStorage now uses saveMetadata/getMetadata for key-value storage
saveMetadata: vi.fn(async (key: string, data: any) => {
mockStorage.set(key, JSON.stringify(data))
}),
getMetadata: vi.fn(async (key: string) => {
const data = mockStorage.get(key)
if (!data) return null
return JSON.parse(data)
}),
// Legacy methods for compatibility
exists: vi.fn(async (path: string) => mockStorage.has(path)),
writeFile: vi.fn(async (path: string, data: string) => {
mockStorage.set(path, data)
}),
readFile: vi.fn(async (path: string) => {
const data = mockStorage.get(path)
if (!data) throw new Error('File not found')
return data
}),
deleteFile: vi.fn(async (path: string) => {
mockStorage.delete(path)
})
},
refManager: {
getRef: vi.fn(async (branch: string) => ({
name: `refs/heads/${branch}`,
commitHash: 'commit-hash-123',
type: 'branch'
})),
setRef: vi.fn(async () => {}),
resolveRef: vi.fn(async () => 'commit-hash-123')
},
getNounMetadata: vi.fn(async (id: string) => {
const entity = mockIndex.get(id)
// Return null for version entities (_version:...) that don't exist
// Throw for regular entities that don't exist
if (!entity) {
if (id.startsWith('_version:')) {
return null // Version doesn't exist - let VersionIndex handle it
}
throw new Error(`Entity ${id} not found`)
}
return entity
}),
saveNounMetadata: vi.fn(async (id: string, data: NounMetadata) => {
mockIndex.set(id, data)
}),
deleteNounMetadata: vi.fn(async (id: string) => {
mockIndex.delete(id)
}),
searchByMetadata: vi.fn(async (query: any) => {
const results: any[] = []
for (const [id, entity] of mockIndex.entries()) {
let matches = true
for (const [key, value] of Object.entries(query)) {
// Handle top-level properties (like 'type')
if (key === 'type') {
if (entity.type !== value) {
matches = false
break
}
continue // Skip metadata check for 'type'
}
// Check metadata properties with glob pattern support
const entityValue = entity.metadata?.[key]
// Support simple glob patterns (e.g., 'v1.*' matches 'v1.0.0', 'v1.1.0')
if (typeof value === 'string' && value.includes('*')) {
const pattern = new RegExp('^' + value.replace(/\*/g, '.*') + '$')
if (!entityValue || !pattern.test(String(entityValue))) {
matches = false
break
}
} else if (entityValue !== value) {
matches = false
break
}
}
if (matches) {
results.push({ id, ...entity })
}
}
return results
}),
commit: vi.fn(async () => 'commit-hash-123'),
// v6.3.0: VersionManager.restore() uses brain.update() to refresh all indexes
update: vi.fn(async (opts: { id: string, data?: any, type?: string, metadata?: any, confidence?: number, weight?: number, merge?: boolean }) => {
// Simulate update by merging metadata into the entity
const existing = mockIndex.get(opts.id)
if (!existing) {
throw new Error(`Entity ${opts.id} not found for update`)
}
const updated = {
...existing,
data: opts.data !== undefined ? opts.data : existing.data,
type: opts.type || existing.type,
confidence: opts.confidence !== undefined ? opts.confidence : existing.confidence,
weight: opts.weight !== undefined ? opts.weight : existing.weight,
...(opts.merge === false ? opts.metadata : { ...existing.metadata, ...opts.metadata })
}
mockIndex.set(opts.id, updated)
})
}
manager = new VersionManager(mockBrain)
})
describe('save()', () => {
it('should save a new version', async () => {
// Add test entity
mockIndex.set('user-123', {
id: 'user-123',
type: 'user',
name: 'Alice',
metadata: { email: 'alice@example.com' }
})
const version = await manager.save('user-123', {
tag: 'v1.0',
description: 'Initial version'
})
expect(version.version).toBe(1)
expect(version.entityId).toBe('user-123')
expect(version.branch).toBe('main')
expect(version.tag).toBe('v1.0')
expect(version.description).toBe('Initial version')
expect(version.contentHash).toBeDefined()
expect(version.commitHash).toBe('commit-hash-123')
})
it('should increment version numbers', async () => {
mockIndex.set('doc-1', {
id: 'doc-1',
type: 'document',
name: 'Doc',
metadata: { content: 'Version 1' }
})
const v1 = await manager.save('doc-1', { tag: 'v1' })
expect(v1.version).toBe(1)
// Update entity
mockIndex.set('doc-1', {
id: 'doc-1',
type: 'document',
name: 'Doc',
metadata: { content: 'Version 2' }
})
const v2 = await manager.save('doc-1', { tag: 'v2' })
expect(v2.version).toBe(2)
mockIndex.set('doc-1', {
id: 'doc-1',
type: 'document',
name: 'Doc',
metadata: { content: 'Version 3' }
})
const v3 = await manager.save('doc-1', { tag: 'v3' })
expect(v3.version).toBe(3)
})
it('should deduplicate identical content', async () => {
mockIndex.set('note-1', {
id: 'note-1',
type: 'document',
name: 'Note',
metadata: { content: 'Unchanged' }
})
const v1 = await manager.save('note-1', { tag: 'v1' })
const v2 = await manager.save('note-1', { tag: 'v2' })
// Should return same version (content unchanged)
expect(v2.version).toBe(v1.version)
expect(v2.contentHash).toBe(v1.contentHash)
})
it('should throw if entity does not exist', async () => {
await expect(
manager.save('nonexistent', { tag: 'v1' })
).rejects.toThrow('Entity nonexistent not found')
})
it('should save without tag or description', async () => {
mockIndex.set('test-1', {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: {}
})
const version = await manager.save('test-1')
expect(version.version).toBe(1)
expect(version.tag).toBeUndefined()
expect(version.description).toBeUndefined()
})
})
describe('restore()', () => {
it('should restore entity to specific version', async () => {
// Save version 1
mockIndex.set('config-1', {
id: 'config-1',
type: 'thing',
name: 'Config',
metadata: { theme: 'light', version: 1 }
})
await manager.save('config-1', { tag: 'v1' })
// Update to version 2
mockIndex.set('config-1', {
id: 'config-1',
type: 'thing',
name: 'Config',
metadata: { theme: 'dark', version: 2 }
})
await manager.save('config-1', { tag: 'v2' })
// Restore to v1
await manager.restore('config-1', 1)
// v6.3.0: restore() uses brain.update() to refresh all indexes
expect(mockBrain.update).toHaveBeenCalledWith(
expect.objectContaining({
id: 'config-1',
merge: false // Replace, don't merge
})
)
})
it('should restore by tag', async () => {
mockIndex.set('app-1', {
id: 'app-1',
type: 'thing',
name: 'App',
metadata: { status: 'alpha' }
})
await manager.save('app-1', { tag: 'alpha' })
mockIndex.set('app-1', {
id: 'app-1',
type: 'thing',
name: 'App',
metadata: { status: 'beta' }
})
await manager.save('app-1', { tag: 'beta' })
// Restore to alpha
await manager.restore('app-1', 'alpha')
// v6.3.0: restore() uses brain.update() to refresh all indexes
expect(mockBrain.update).toHaveBeenCalledWith(
expect.objectContaining({
id: 'app-1',
merge: false // Replace, don't merge
})
)
})
it('should throw if version not found', async () => {
mockIndex.set('test-1', {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: {}
})
await manager.save('test-1')
await expect(
manager.restore('test-1', 999)
).rejects.toThrow('Version 999 not found')
})
})
describe('list()', () => {
it('should list all versions for entity', async () => {
mockIndex.set('log-1', {
id: 'log-1',
type: 'document',
name: 'Log',
metadata: { entry: 1 }
})
await manager.save('log-1', { tag: 'v1' })
mockIndex.set('log-1', {
id: 'log-1',
type: 'document',
name: 'Log',
metadata: { entry: 2 }
})
await manager.save('log-1', { tag: 'v2' })
mockIndex.set('log-1', {
id: 'log-1',
type: 'document',
name: 'Log',
metadata: { entry: 3 }
})
await manager.save('log-1', { tag: 'v3' })
const versions = await manager.list('log-1')
expect(versions).toHaveLength(3)
expect(versions[0].version).toBe(3) // Newest first
expect(versions[1].version).toBe(2)
expect(versions[2].version).toBe(1)
})
it('should filter by exact tag', async () => {
// v6.3.0: Tag filtering is exact match only (no glob patterns)
mockIndex.set('app-1', {
id: 'app-1',
type: 'thing',
name: 'App',
metadata: { v: 1 }
})
await manager.save('app-1', { tag: 'v1.0.0' })
mockIndex.set('app-1', {
id: 'app-1',
type: 'thing',
name: 'App',
metadata: { v: 2 }
})
await manager.save('app-1', { tag: 'v1.1.0' })
mockIndex.set('app-1', {
id: 'app-1',
type: 'thing',
name: 'App',
metadata: { v: 3 }
})
await manager.save('app-1', { tag: 'v2.0.0' })
// v6.3.0: Exact tag match only
const v1Versions = await manager.list('app-1', { tag: 'v1.0.0' })
expect(v1Versions).toHaveLength(1)
expect(v1Versions[0].tag).toBe('v1.0.0')
// Get all versions
const allVersions = await manager.list('app-1')
expect(allVersions).toHaveLength(3)
})
it('should limit results', async () => {
mockIndex.set('data-1', {
id: 'data-1',
type: 'thing',
name: 'Data',
metadata: { v: 1 }
})
for (let i = 1; i <= 5; i++) {
mockIndex.set('data-1', {
id: 'data-1',
type: 'thing',
name: 'Data',
metadata: { v: i }
})
await manager.save('data-1', { tag: `v${i}` })
}
const versions = await manager.list('data-1', { limit: 3 })
expect(versions).toHaveLength(3)
expect(versions[0].version).toBe(5)
expect(versions[1].version).toBe(4)
expect(versions[2].version).toBe(3)
})
it('should return empty array if no versions', async () => {
mockIndex.set('new-1', {
id: 'new-1',
type: 'thing',
name: 'New',
metadata: {}
})
const versions = await manager.list('new-1')
expect(versions).toHaveLength(0)
})
})
describe('compare()', () => {
it('should compare two versions', async () => {
mockIndex.set('user-1', {
id: 'user-1',
type: 'user',
name: 'Bob',
metadata: { email: 'bob@example.com', age: 30 }
})
await manager.save('user-1', { tag: 'v1' })
mockIndex.set('user-1', {
id: 'user-1',
type: 'user',
name: 'Robert',
metadata: { email: 'robert@example.com', age: 30, city: 'NYC' }
})
await manager.save('user-1', { tag: 'v2' })
const diff = await manager.compare('user-1', 1, 2)
expect(diff.totalChanges).toBeGreaterThan(0)
expect(diff.modified.length).toBeGreaterThan(0)
expect(diff.added.length).toBeGreaterThan(0)
const nameChange = diff.modified.find(c => c.path.includes('name'))
expect(nameChange?.oldValue).toBe('Bob')
expect(nameChange?.newValue).toBe('Robert')
const cityAdd = diff.added.find(c => c.path.includes('city'))
expect(cityAdd?.newValue).toBe('NYC')
})
it('should compare by tags', async () => {
mockIndex.set('doc-1', {
id: 'doc-1',
type: 'document',
name: 'Doc',
metadata: { content: 'Alpha' }
})
await manager.save('doc-1', { tag: 'alpha' })
mockIndex.set('doc-1', {
id: 'doc-1',
type: 'document',
name: 'Doc',
metadata: { content: 'Beta' }
})
await manager.save('doc-1', { tag: 'beta' })
const diff = await manager.compare('doc-1', 'alpha', 'beta')
expect(diff.modified.length).toBeGreaterThan(0)
const contentChange = diff.modified.find(c => c.path.includes('content'))
expect(contentChange?.oldValue).toBe('Alpha')
expect(contentChange?.newValue).toBe('Beta')
})
it('should detect identical versions', async () => {
mockIndex.set('same-1', {
id: 'same-1',
type: 'thing',
name: 'Same',
metadata: { value: 100 }
})
await manager.save('same-1', { tag: 'v1' })
await manager.save('same-1', { tag: 'v2' }) // Content unchanged
const diff = await manager.compare('same-1', 1, 1)
expect(diff.identical).toBe(true)
expect(diff.totalChanges).toBe(0)
})
})
describe('prune()', () => {
it('should prune old versions keeping recent', async () => {
mockIndex.set('log-1', {
id: 'log-1',
type: 'document',
name: 'Log',
metadata: { entry: 1 }
})
for (let i = 1; i <= 10; i++) {
mockIndex.set('log-1', {
id: 'log-1',
type: 'document',
name: 'Log',
metadata: { entry: i }
})
await manager.save('log-1', { tag: `v${i}` })
}
const result = await manager.prune('log-1', {
keepRecent: 5,
keepTagged: false
})
expect(result.deleted).toBe(5)
expect(result.kept).toBe(5)
const remaining = await manager.list('log-1')
expect(remaining).toHaveLength(5)
expect(remaining[0].version).toBe(10) // Most recent
})
it('should keep tagged versions', async () => {
mockIndex.set('app-1', {
id: 'app-1',
type: 'thing',
name: 'App',
metadata: { v: 1 }
})
await manager.save('app-1', { tag: 'release' })
for (let i = 2; i <= 10; i++) {
mockIndex.set('app-1', {
id: 'app-1',
type: 'thing',
name: 'App',
metadata: { v: i }
})
await manager.save('app-1') // No tag
}
const result = await manager.prune('app-1', {
keepRecent: 3,
keepTagged: true
})
const remaining = await manager.list('app-1')
const releaseVersion = remaining.find(v => v.tag === 'release')
expect(releaseVersion).toBeDefined()
})
it('should respect keepAfter timestamp', async () => {
mockIndex.set('data-1', {
id: 'data-1',
type: 'thing',
name: 'Data',
metadata: { v: 1 }
})
const now = Date.now()
const oneDayAgo = now - 24 * 60 * 60 * 1000
await manager.save('data-1', { tag: 'old' })
// Simulate newer versions
for (let i = 2; i <= 5; i++) {
mockIndex.set('data-1', {
id: 'data-1',
type: 'thing',
name: 'Data',
metadata: { v: i }
})
await manager.save('data-1', { tag: `new${i}` })
}
const result = await manager.prune('data-1', {
keepAfter: oneDayAgo,
keepTagged: false
})
expect(result.deleted).toBeGreaterThanOrEqual(0)
})
})
describe('getVersion()', () => {
it('should get specific version by number', async () => {
mockIndex.set('test-1', {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: { v: 1 }
})
const v1 = await manager.save('test-1', { tag: 'v1' })
mockIndex.set('test-1', {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: { v: 2 }
})
await manager.save('test-1', { tag: 'v2' })
const version = await manager.getVersion('test-1', 1)
expect(version).toBeDefined()
expect(version?.version).toBe(1)
expect(version?.tag).toBe('v1')
})
it('should return null if version not found', async () => {
mockIndex.set('test-1', {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: {}
})
await manager.save('test-1')
const version = await manager.getVersion('test-1', 999)
expect(version).toBeNull()
})
})
describe('getVersionByTag()', () => {
it('should get version by tag', async () => {
mockIndex.set('app-1', {
id: 'app-1',
type: 'thing',
name: 'App',
metadata: { status: 'alpha' }
})
await manager.save('app-1', { tag: 'alpha' })
mockIndex.set('app-1', {
id: 'app-1',
type: 'thing',
name: 'App',
metadata: { status: 'beta' }
})
await manager.save('app-1', { tag: 'beta' })
const betaVersion = await manager.getVersionByTag('app-1', 'beta')
expect(betaVersion).toBeDefined()
expect(betaVersion?.tag).toBe('beta')
})
it('should return null if tag not found', async () => {
mockIndex.set('test-1', {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: {}
})
await manager.save('test-1', { tag: 'v1' })
const version = await manager.getVersionByTag('test-1', 'nonexistent')
expect(version).toBeNull()
})
})
describe('getVersionCount()', () => {
it('should count versions', async () => {
mockIndex.set('doc-1', {
id: 'doc-1',
type: 'document',
name: 'Doc',
metadata: { v: 1 }
})
expect(await manager.getVersionCount('doc-1')).toBe(0)
await manager.save('doc-1')
expect(await manager.getVersionCount('doc-1')).toBe(1)
mockIndex.set('doc-1', {
id: 'doc-1',
type: 'document',
name: 'Doc',
metadata: { v: 2 }
})
await manager.save('doc-1')
expect(await manager.getVersionCount('doc-1')).toBe(2)
})
})
describe('Branch Awareness', () => {
it('should track versions per branch', async () => {
mockIndex.set('branch-test', {
id: 'branch-test',
type: 'thing',
name: 'Test',
metadata: {}
})
// Save on main
mockBrain.currentBranch = 'main'
const mainV1 = await manager.save('branch-test', { tag: 'main-v1' })
expect(mainV1.branch).toBe('main')
// Save on feature
mockBrain.currentBranch = 'feature'
const featureV1 = await manager.save('branch-test', { tag: 'feature-v1' })
expect(featureV1.branch).toBe('feature')
// Versions should be independent
expect(mainV1.version).toBe(1)
expect(featureV1.version).toBe(1) // Each branch starts at 1
})
})
})

567
tests/unit/versioning/VersionStorage.test.ts
View file

@ -1,567 +0,0 @@
/**
* VersionStorage Unit Tests (v5.3.0)
*
* Tests content-addressable storage:
* - SHA-256 content hashing
* - Content deduplication
* - Storage adapter integration
* - Save/load/delete operations
*/
import { describe, it, expect, beforeEach, vi } from 'vitest'
import { VersionStorage } from '../../../src/versioning/VersionStorage.js'
import type { NounMetadata } from '../../../src/coreTypes.js'
import type { EntityVersion } from '../../../src/versioning/VersionManager.js'
describe('VersionStorage', () => {
let storage: VersionStorage
let mockBrain: any
let mockFiles: Map<string, string>
beforeEach(() => {
mockFiles = new Map()
mockBrain = {
storageAdapter: {
// v6.3.0: VersionStorage now uses saveMetadata/getMetadata instead of writeFile/readFile
saveMetadata: vi.fn(async (key: string, data: any) => {
mockFiles.set(key, JSON.stringify(data))
}),
getMetadata: vi.fn(async (key: string) => {
const data = mockFiles.get(key)
if (!data) return null
return JSON.parse(data)
}),
// Legacy methods for tests that still use them
exists: vi.fn(async (path: string) => mockFiles.has(path)),
writeFile: vi.fn(async (path: string, data: string) => {
mockFiles.set(path, data)
}),
readFile: vi.fn(async (path: string) => {
const data = mockFiles.get(path)
if (!data) throw new Error('File not found')
return data
}),
deleteFile: vi.fn(async (path: string) => {
mockFiles.delete(path)
})
}
}
storage = new VersionStorage(mockBrain)
})
describe('hashEntity()', () => {
it('should generate consistent SHA-256 hashes', () => {
const entity: NounMetadata = {
id: 'user-123',
type: 'user',
name: 'Alice',
metadata: { email: 'alice@example.com' }
}
const hash1 = storage.hashEntity(entity)
const hash2 = storage.hashEntity(entity)
expect(hash1).toBe(hash2)
expect(hash1).toHaveLength(64) // SHA-256 = 64 hex chars
})
it('should generate different hashes for different content', () => {
const entity1: NounMetadata = {
id: 'user-1',
type: 'user',
name: 'Alice',
metadata: {}
}
const entity2: NounMetadata = {
id: 'user-1',
type: 'user',
name: 'Bob',
metadata: {}
}
const hash1 = storage.hashEntity(entity1)
const hash2 = storage.hashEntity(entity2)
expect(hash1).not.toBe(hash2)
})
it('should ignore property order (stable JSON)', () => {
const entity1: NounMetadata = {
id: 'user-1',
type: 'user',
name: 'Alice',
metadata: { a: 1, b: 2, c: 3 }
}
const entity2: NounMetadata = {
type: 'user',
metadata: { c: 3, b: 2, a: 1 },
name: 'Alice',
id: 'user-1'
}
const hash1 = storage.hashEntity(entity1)
const hash2 = storage.hashEntity(entity2)
expect(hash1).toBe(hash2)
})
it('should handle nested objects', () => {
const entity: NounMetadata = {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: {
nested: {
deep: {
value: 'hello'
}
}
}
}
const hash = storage.hashEntity(entity)
expect(hash).toHaveLength(64)
})
it('should handle arrays', () => {
const entity: NounMetadata = {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: {
tags: ['a', 'b', 'c']
}
}
const hash = storage.hashEntity(entity)
expect(hash).toHaveLength(64)
})
it('should handle null and undefined', () => {
const entity1: NounMetadata = {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: { value: null }
}
const entity2: NounMetadata = {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: { value: undefined }
}
const hash1 = storage.hashEntity(entity1)
const hash2 = storage.hashEntity(entity2)
expect(hash1).not.toBe(hash2)
})
})
describe('saveVersion()', () => {
it('should save version content to storage', async () => {
const entity: NounMetadata = {
id: 'user-123',
type: 'user',
name: 'Alice',
metadata: { email: 'alice@example.com' }
}
const version: EntityVersion = {
version: 1,
entityId: 'user-123',
branch: 'main',
commitHash: 'commit-123',
timestamp: Date.now(),
contentHash: storage.hashEntity(entity)
}
await storage.saveVersion(version, entity)
// v6.3.0: Uses __system_version_ prefix for saveMetadata keys
const expectedKey = `__system_version_user-123_${version.contentHash}`
expect(mockFiles.has(expectedKey)).toBe(true)
const savedData = mockFiles.get(expectedKey)
expect(savedData).toBeDefined()
expect(JSON.parse(savedData!)).toEqual(entity)
})
it('should deduplicate identical content', async () => {
const entity: NounMetadata = {
id: 'doc-1',
type: 'document',
name: 'Doc',
metadata: { content: 'Same content' }
}
const contentHash = storage.hashEntity(entity)
const version1: EntityVersion = {
version: 1,
entityId: 'doc-1',
branch: 'main',
commitHash: 'commit-1',
timestamp: Date.now(),
contentHash
}
const version2: EntityVersion = {
version: 2,
entityId: 'doc-1',
branch: 'main',
commitHash: 'commit-2',
timestamp: Date.now() + 1000,
contentHash // Same hash!
}
await storage.saveVersion(version1, entity)
const writeCallCount1 = mockBrain.storageAdapter.writeFile.mock.calls.length
await storage.saveVersion(version2, entity)
const writeCallCount2 = mockBrain.storageAdapter.writeFile.mock.calls.length
// Should not write again (deduplication)
expect(writeCallCount2).toBe(writeCallCount1)
})
it('should store different content separately', async () => {
const entity1: NounMetadata = {
id: 'doc-1',
type: 'document',
name: 'Doc',
metadata: { content: 'Version 1' }
}
const entity2: NounMetadata = {
id: 'doc-1',
type: 'document',
name: 'Doc',
metadata: { content: 'Version 2' }
}
const version1: EntityVersion = {
version: 1,
entityId: 'doc-1',
branch: 'main',
commitHash: 'commit-1',
timestamp: Date.now(),
contentHash: storage.hashEntity(entity1)
}
const version2: EntityVersion = {
version: 2,
entityId: 'doc-1',
branch: 'main',
commitHash: 'commit-2',
timestamp: Date.now() + 1000,
contentHash: storage.hashEntity(entity2)
}
await storage.saveVersion(version1, entity1)
await storage.saveVersion(version2, entity2)
// v6.3.0: Uses __system_version_ prefix for saveMetadata keys
const key1 = `__system_version_doc-1_${version1.contentHash}`
const key2 = `__system_version_doc-1_${version2.contentHash}`
expect(mockFiles.has(key1)).toBe(true)
expect(mockFiles.has(key2)).toBe(true)
expect(key1).not.toBe(key2)
})
})
describe('loadVersion()', () => {
it('should load version content from storage', async () => {
const entity: NounMetadata = {
id: 'user-123',
type: 'user',
name: 'Alice',
metadata: { email: 'alice@example.com' }
}
const version: EntityVersion = {
version: 1,
entityId: 'user-123',
branch: 'main',
commitHash: 'commit-123',
timestamp: Date.now(),
contentHash: storage.hashEntity(entity)
}
// Save first
await storage.saveVersion(version, entity)
// Load
const loaded = await storage.loadVersion(version)
expect(loaded).toEqual(entity)
})
it('should return null if version not found', async () => {
const version: EntityVersion = {
version: 1,
entityId: 'nonexistent',
branch: 'main',
commitHash: 'commit-123',
timestamp: Date.now(),
contentHash: 'fake-hash'
}
const loaded = await storage.loadVersion(version)
expect(loaded).toBeNull()
})
it('should handle complex nested data', async () => {
const entity: NounMetadata = {
id: 'complex-1',
type: 'thing',
name: 'Complex',
metadata: {
nested: {
array: [1, 2, 3],
object: { key: 'value' }
},
tags: ['a', 'b', 'c']
}
}
const version: EntityVersion = {
version: 1,
entityId: 'complex-1',
branch: 'main',
commitHash: 'commit-123',
timestamp: Date.now(),
contentHash: storage.hashEntity(entity)
}
await storage.saveVersion(version, entity)
const loaded = await storage.loadVersion(version)
expect(loaded).toEqual(entity)
})
})
describe('deleteVersion()', () => {
it('should handle version deletion (content-addressed, no-op)', async () => {
// v6.3.0: Version content is content-addressed and may be shared by multiple versions.
// The deleteVersion method is a no-op - it doesn't actually delete the content.
// Version INDEX is deleted via VersionIndex.removeVersion().
// A GC process could clean up unreferenced content in the future.
const entity: NounMetadata = {
id: 'user-123',
type: 'user',
name: 'Alice',
metadata: {}
}
const version: EntityVersion = {
version: 1,
entityId: 'user-123',
branch: 'main',
commitHash: 'commit-123',
timestamp: Date.now(),
contentHash: storage.hashEntity(entity)
}
// Save
await storage.saveVersion(version, entity)
const key = `__system_version_user-123_${version.contentHash}`
expect(mockFiles.has(key)).toBe(true)
// Delete is a no-op for content (content-addressed, may be shared)
await storage.deleteVersion(version)
// Content is NOT deleted to avoid breaking other versions with same content hash
expect(mockFiles.has(key)).toBe(true) // v6.3.0: Content preserved
})
it('should handle deleting non-existent version gracefully', async () => {
const version: EntityVersion = {
version: 1,
entityId: 'nonexistent',
branch: 'main',
commitHash: 'commit-123',
timestamp: Date.now(),
contentHash: 'fake-hash'
}
// Should not throw
await storage.deleteVersion(version)
})
})
describe('Storage Adapter Integration', () => {
it('should work with memory storage adapter', async () => {
const entity: NounMetadata = {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: { value: 123 }
}
const version: EntityVersion = {
version: 1,
entityId: 'test-1',
branch: 'main',
commitHash: 'commit-123',
timestamp: Date.now(),
contentHash: storage.hashEntity(entity)
}
await storage.saveVersion(version, entity)
const loaded = await storage.loadVersion(version)
expect(loaded).toEqual(entity)
})
it('should use adapter.saveMetadata API', async () => {
// v6.3.0: VersionStorage now uses saveMetadata/getMetadata exclusively
const testStorage = new Map<string, string>()
mockBrain.storageAdapter = {
saveMetadata: vi.fn(async (key: string, data: any) => {
testStorage.set(key, JSON.stringify(data))
}),
getMetadata: vi.fn(async (key: string) => {
const data = testStorage.get(key)
if (!data) return null
return JSON.parse(data)
})
}
storage = new VersionStorage(mockBrain)
const entity: NounMetadata = {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: {}
}
const version: EntityVersion = {
version: 1,
entityId: 'test-1',
branch: 'main',
commitHash: 'commit-123',
timestamp: Date.now(),
contentHash: storage.hashEntity(entity)
}
await storage.saveVersion(version, entity)
expect(mockBrain.storageAdapter.saveMetadata).toHaveBeenCalled()
const loaded = await storage.loadVersion(version)
expect(mockBrain.storageAdapter.getMetadata).toHaveBeenCalled()
expect(loaded).toEqual(entity)
})
it('should throw if storage adapter missing', async () => {
mockBrain.storageAdapter = null
storage = new VersionStorage(mockBrain)
const entity: NounMetadata = {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: {}
}
const version: EntityVersion = {
version: 1,
entityId: 'test-1',
branch: 'main',
commitHash: 'commit-123',
timestamp: Date.now(),
contentHash: storage.hashEntity(entity)
}
await expect(
storage.saveVersion(version, entity)
).rejects.toThrow('Storage adapter not available')
})
it('should throw if adapter does not support required operations', async () => {
mockBrain.storageAdapter = {} // No methods (no saveMetadata)
storage = new VersionStorage(mockBrain)
const entity: NounMetadata = {
id: 'test-1',
type: 'thing',
name: 'Test',
metadata: {}
}
const version: EntityVersion = {
version: 1,
entityId: 'test-1',
branch: 'main',
commitHash: 'commit-123',
timestamp: Date.now(),
contentHash: storage.hashEntity(entity)
}
// v6.3.0: Error from calling undefined saveMetadata
await expect(
storage.saveVersion(version, entity)
).rejects.toThrow() // TypeError: adapter.saveMetadata is not a function
})
})
describe('Key Generation', () => {
it('should generate correct storage keys', async () => {
const entity: NounMetadata = {
id: 'user-123',
type: 'user',
name: 'Alice',
metadata: {}
}
const contentHash = storage.hashEntity(entity)
const version: EntityVersion = {
version: 1,
entityId: 'user-123',
branch: 'main',
commitHash: 'commit-123',
timestamp: Date.now(),
contentHash
}
await storage.saveVersion(version, entity)
// v6.3.0: Uses __system_version_ prefix for saveMetadata keys
const expectedKey = `__system_version_user-123_${contentHash}`
expect(mockFiles.has(expectedKey)).toBe(true)
})
it('should handle entity IDs with special characters', async () => {
const entity: NounMetadata = {
id: 'user:123:profile',
type: 'user',
name: 'Alice',
metadata: {}
}
const contentHash = storage.hashEntity(entity)
const version: EntityVersion = {
version: 1,
entityId: 'user:123:profile',
branch: 'main',
commitHash: 'commit-123',
timestamp: Date.now(),
contentHash
}
await storage.saveVersion(version, entity)
// v6.3.0: Uses __system_version_ prefix for saveMetadata keys
const expectedKey = `__system_version_user:123:profile_${contentHash}`
expect(mockFiles.has(expectedKey)).toBe(true)
})
})
})