docs(8.0): consistency-model concept + snapshots guide — Db API replaces branching docs

docs/BATCHING.md

@@ -77,7 +77,7 @@ for (const [id, metadata] of metadataMap) {
 **Features:**
 - ✅ Direct O(1) path construction from ID (no type lookup needed!)
 - ✅ Sharding preservation (all paths include `{shard}/{id}`)
-- ✅ COW-aware (respects branch paths)
+- ✅ Write-cache coherent (read-after-write consistency)
 - ✅ 40x faster than v5.x type-first architecture
 
 **Performance:**
@@ -126,32 +126,6 @@ for (const [sourceId, verbs] of results) {
 
 ---
 
-### 4. `storage.readBatchWithInheritance(paths, targetBranch?)`
-
-COW-aware batch path resolution with branch inheritance.
-
-```typescript
-const storage = brain.storage as BaseStorage
-
-const paths = [
- 'entities/nouns/{shard}/id1/metadata.json',
- 'entities/nouns/{shard}/id2/metadata.json'
-]
-
-// Resolves to: branches/{branch}/entities/nouns/{shard}/{id}/metadata.json
-const results: Map<string, any> = await storage.readBatchWithInheritance(paths, 'my-branch')
-
-// Automatically inherits from parent branches for missing entities
-```
-
-**Features:**
-- ✅ Branch path resolution (`branches/{branch}/...`)
-- ✅ Write cache integration (read-after-write consistency)
-- ✅ COW inheritance (fallback to parent commits for missing entities)
-- ✅ Adapter-agnostic (works with all storage adapters)
-
----
-
 ## VFS Integration
 
 VFS operations automatically use batch APIs for maximum performance.
@@ -229,62 +203,21 @@ const path = `entities/nouns/${shard}/${id}/metadata.json`
 
 ---
 
-### ✅ COW (Copy-on-Write)
+### ✅ Generational MVCC (8.0)
 
-Batch operations respect branch isolation and time-travel:
+Batch reads always serve the **live** generation through the fast paths
+shown above. Point-in-time reads go through the Db API instead: a pinned
+`Db` (`brain.now()`, `brain.asOf()`) resolves changed ids from immutable
+generation records and unchanged ids from the same live paths batch reads
+use — see the [consistency model](concepts/consistency-model.md).
 
 ```typescript
-// Main branch
-const brain = await Brainy.create({ enableCOW: true })
-await brain.add({ type: 'document', data: 'Main' })
-
-// Create fork
-const fork = await brain.fork('experiment')
-
-// Batch operations are isolated
-await brain.batchGet([id1, id2]) // → Reads from: branches/main/...
-await fork.batchGet([id1, id2]) // → Reads from: branches/experiment/...
+const db = brain.now()                       // pinned view
+const entity = await db.get(id)              // correct at the pinned generation
+const results = await brain.batchGet(ids)    // live state, batched
+await db.release()
 ```
 
-**Inheritance:**
-- Entities missing from child branch automatically inherit from parent commits
-- `readBatchWithInheritance()` walks commit history for missing items
-- Preserves fork semantics while maintaining performance
-
----
-
-### ✅ fork() and checkout()
-
-```typescript
-const fork = await brain.fork('my-branch')
-await fork.add({ type: 'document', data: 'Fork entity' })
-
-// Batch operations use correct branch
-const results = await fork.batchGet([id1, id2])
-// → Reads from: branches/my-branch/...
-
-// Checkout changes active branch
-await fork.checkout('main')
-const mainResults = await fork.batchGet([id1, id2])
-// → Reads from: branches/main/...
-```
-
----
-
-### ✅ asOf() Time-Travel
-
-```typescript
-// Create historical snapshot
-await brain.commit('v1.0')
-const snapshot = await brain.asOf('v1.0')
-
-// Batch operations on historical data
-const results = await snapshot.batchGet([id1, id2])
-// → Reads from historical tree state
-```
-
-Historical queries use `HistoricalStorageAdapter` which wraps batch operations to point at specific commits.
-
 ---
 
 ## Performance Benchmarks
@@ -490,8 +423,6 @@ High-Level API (src/brainy.ts)
  ↓
 Storage Layer (src/storage/baseStorage.ts)
  ↓
-COW Layer (readBatchWithInheritance)
- ↓
 Adapter Layer (readBatchFromAdapter)
  ↓
 Storage Adapter (FileSystemStorage / MemoryStorage)
@@ -509,7 +440,6 @@ return await Promise.all(resolvedPaths.map(path => this.read(path)))
 **Shipped Adapters:**
 - MemoryStorage
 - FileSystemStorage
-- HistoricalStorageAdapter (delegates to underlying)
 
 ---
 
@@ -518,7 +448,6 @@ return await Promise.all(resolvedPaths.map(path => this.read(path)))
 - `brain.batchGet(ids, options?)` - High-level batch entity retrieval
 - `storage.getNounMetadataBatch(ids)` - Storage-level metadata batch
 - `storage.getVerbsBySourceBatch(sourceIds, verbType?)` - Batch relationship queries
-- `storage.readBatchWithInheritance(paths, targetBranch?)` - COW-aware batch reads
 
 **Performance Improvements:**
 - VFS operations: 90%+ faster than the naive per-entity loop
@@ -528,10 +457,8 @@ return await Promise.all(resolvedPaths.map(path => this.read(path)))
 **Compatibility:**
 - ✅ ID-first storage
 - ✅ Sharding (256 shards)
-- ✅ COW (branch isolation, inheritance)
-- ✅ fork() and checkout()
-- ✅ asOf() time-travel
-- ✅ All indexes respected (vector, type-aware vector, metadata, graph adjacency, version, deleted items)
+- ✅ Generational MVCC — batch reads serve the live generation; pinned `Db` views serve the past
+- ✅ All indexes respected (vector, metadata, graph adjacency)
 
 ---