docs(8.0): consistency-model concept + snapshots guide — Db API replaces branching docs
This commit is contained in:
parent
e5feae4104
commit
cc8037db10
23 changed files with 1053 additions and 1871 deletions
|
|
@ -5,7 +5,7 @@ public: true
|
|||
category: api
|
||||
template: api
|
||||
order: 1
|
||||
description: Complete API reference for all Brainy methods — add, find, relate, update, delete, batch operations, branching, entity versioning, VFS, neural API, and more.
|
||||
description: Complete API reference for all Brainy methods — add, find, relate, update, delete, batch operations, the Db API (transactions, snapshots, time travel), VFS, neural API, and more.
|
||||
next:
|
||||
- getting-started/quick-start
|
||||
- guides/find-system
|
||||
|
|
@ -14,9 +14,9 @@ next:
|
|||
# 🧠 Brainy API Reference
|
||||
|
||||
> **Complete API documentation for Brainy**
|
||||
> Zero Configuration • Triple Intelligence • Git-Style Branching • Entity Versioning • Candle WASM Embeddings
|
||||
> Zero Configuration • Triple Intelligence • Database as a Value • Atomic Transactions • Time Travel
|
||||
|
||||
**Updated:** 2026-01-06
|
||||
**Updated:** 2026-06-11
|
||||
**All APIs verified against actual code**
|
||||
|
||||
---
|
||||
|
|
@ -43,15 +43,19 @@ const results = await brain.find({
|
|||
connected: { from: id, depth: 2 }
|
||||
})
|
||||
|
||||
// Fork for safe experimentation
|
||||
const experiment = await brain.fork('test-feature')
|
||||
await experiment.add({ data: 'test', type: NounType.Document })
|
||||
await experiment.commit({ message: 'Add test data' })
|
||||
// Pin the current state as an immutable value
|
||||
const db = brain.now()
|
||||
|
||||
// Entity versioning
|
||||
await brain.versions.save(id, { tag: 'v1.0', description: 'Initial version' })
|
||||
await brain.update(id, { category: 'AI' })
|
||||
await brain.versions.save(id, { tag: 'v2.0' })
|
||||
// Commit an atomic multi-write batch (all-or-nothing)
|
||||
await brain.transact([
|
||||
{ op: 'update', id, metadata: { category: 'AI' } }
|
||||
], { meta: { author: 'docs-example' } })
|
||||
|
||||
await db.get(id) // still sees the pre-transaction state — snapshot isolation
|
||||
await db.release()
|
||||
|
||||
// Time travel: query any past state
|
||||
const yesterday = await brain.asOf(new Date(Date.now() - 86_400_000))
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -73,11 +77,8 @@ See **[Data Model](../DATA_MODEL.md)** for the full explanation.
|
|||
### 🧠 Triple Intelligence
|
||||
Vector search + Graph traversal + Metadata filtering in one unified query.
|
||||
|
||||
### 🌳 Git-Style Branching
|
||||
Fork, experiment, and commit - Snowflake-style copy-on-write isolation.
|
||||
|
||||
### 📜 Entity Versioning
|
||||
Time-travel and history tracking for individual entities - Git-like version control with content-addressable storage.
|
||||
### 🧊 Database Values (Db)
|
||||
The whole store pinned as an immutable value — snapshot isolation, atomic `transact()` batches, time travel with `asOf()`, instant hard-link snapshots with `persist()`. See the [consistency model](../concepts/consistency-model.md).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -88,8 +89,7 @@ Time-travel and history tracking for individual entities - Git-like version cont
|
|||
- [Aggregation Engine](#aggregation-engine)
|
||||
- [Relationships](#relationships)
|
||||
- [Batch Operations](#batch-operations)
|
||||
- [Branch Management](#branch-management)
|
||||
- [Entity Versioning](#entity-versioning)
|
||||
- [Database Values & Time Travel (Db API)](#database-values--time-travel-db-api)
|
||||
- [Virtual Filesystem (VFS)](#virtual-filesystem-vfs)
|
||||
- [Neural API](#neural-api)
|
||||
- [Import & Export](#import--export)
|
||||
|
|
@ -781,576 +781,224 @@ const ids = await brain.relateMany({
|
|||
|
||||
---
|
||||
|
||||
## Branch Management
|
||||
## Database Values & Time Travel (Db API)
|
||||
|
||||
Git-style branching with Snowflake-style copy-on-write.
|
||||
Brainy 8.0's generational MVCC exposes the whole store as an immutable
|
||||
value: the **`Db`**. Pin the current state in O(1), commit atomic
|
||||
multi-write batches, query any past generation with the full query surface,
|
||||
cut instant snapshots, and ask what-if questions in memory. The exact
|
||||
guarantees live in the **[consistency model](../concepts/consistency-model.md)**;
|
||||
recipes live in **[Snapshots & Time Travel](../guides/snapshots-and-time-travel.md)**.
|
||||
|
||||
### `fork(branch?, options?)` → `Promise<Brainy>`
|
||||
### `generation()` → `number`
|
||||
|
||||
Create an instant fork (<100ms) with full isolation.
|
||||
The store's current generation — a monotonic watermark advanced once per
|
||||
committed `transact()` batch and once per single-operation write. Never
|
||||
reissued, including across restarts and `restore()`.
|
||||
|
||||
```typescript
|
||||
// Create a fork
|
||||
const experiment = await brain.fork('test-feature')
|
||||
|
||||
// Make changes safely in isolation
|
||||
await experiment.add({ data: 'Test entity', type: NounType.Document })
|
||||
await experiment.update({ id: someId, metadata: { modified: true } })
|
||||
|
||||
// Parent is unaffected!
|
||||
const parentData = await brain.find({}) // Original data unchanged
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `branch?`: `string` - Branch name (auto-generated if omitted)
|
||||
- `options?`: `object`
|
||||
- `description?`: `string` - Branch description
|
||||
|
||||
**Returns:** `Promise<Brainy>` - New Brainy instance on forked branch
|
||||
|
||||
**How it works:** Snowflake-style COW shares the vector index, copies only modified nodes (10-20% memory overhead).
|
||||
|
||||
---
|
||||
|
||||
### `checkout(branch)` → `Promise<void>`
|
||||
|
||||
Switch to a different branch.
|
||||
|
||||
```typescript
|
||||
await brain.checkout('main')
|
||||
await brain.checkout('test-feature')
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `branch`: `string` - Branch name
|
||||
|
||||
---
|
||||
|
||||
### `listBranches()` → `Promise<string[]>`
|
||||
|
||||
List all branches.
|
||||
|
||||
```typescript
|
||||
const branches = await brain.listBranches()
|
||||
// ['main', 'test-feature', 'experiment-2']
|
||||
const g = brain.generation()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `getCurrentBranch()` → `Promise<string>`
|
||||
### `now()` → `Db`
|
||||
|
||||
Get current branch name.
|
||||
Pin the current generation and return an immutable view — O(1), no I/O.
|
||||
The view keeps reading exactly this state no matter what commits afterwards.
|
||||
|
||||
```typescript
|
||||
const current = await brain.getCurrentBranch()
|
||||
// 'main'
|
||||
const db = brain.now()
|
||||
await brain.update({ id, metadata: { v: 2 } })
|
||||
|
||||
await db.get(id) // still sees v: 1 — pinned
|
||||
await brain.get(id) // sees v: 2 — live
|
||||
await db.release() // unpin (enables history compaction)
|
||||
```
|
||||
|
||||
**Returns:** `Db` — release it when done; pins gate `compactHistory()`.
|
||||
|
||||
---
|
||||
|
||||
### `transact(ops, options?)` → `Promise<Db>`
|
||||
|
||||
Execute a declarative operation batch **atomically**: either every
|
||||
operation applies and the store advances exactly one generation, or none
|
||||
apply and the store is byte-identical to its pre-transaction state. The
|
||||
commit point is an atomic manifest rename; a crash anywhere before it rolls
|
||||
back to the exact pre-transaction bytes on the next open.
|
||||
|
||||
```typescript
|
||||
const db = await brain.transact([
|
||||
{ op: 'add', id: orderId, type: NounType.Document, subtype: 'order', data: 'Order #1042' },
|
||||
{ op: 'update', id: customerId, metadata: { lastOrderAt: Date.now() }, ifRev: customer._rev },
|
||||
{ op: 'relate', from: customerId, to: orderId, type: VerbType.Creates, subtype: 'purchase' },
|
||||
{ op: 'remove', id: staleDraftId },
|
||||
{ op: 'unrelate', id: oldRelationId }
|
||||
], {
|
||||
meta: { author: 'order-service', requestId: 'req-9f2' }, // reified, durable
|
||||
ifAtGeneration: expectedGeneration // whole-store CAS
|
||||
})
|
||||
|
||||
db.receipt.ids // resolved id per operation, in input order
|
||||
db.receipt.generation // the committed generation
|
||||
```
|
||||
|
||||
**Operations** (`op` discriminates; parameters mirror the single-operation methods):
|
||||
- `{ op: 'add', ... }` — same parameters as `add()`; optional explicit `id`
|
||||
- `{ op: 'update', ... }` — same parameters as `update()`, including per-entity `ifRev` CAS
|
||||
- `{ op: 'remove', id }` — deletes the entity plus its relationships (same cascade as `delete()`)
|
||||
- `{ op: 'relate', ... }` — same parameters as `relate()`, including `bidirectional`; duplicates dedupe to the existing relationship id
|
||||
- `{ op: 'unrelate', id }` — deletes a relationship by id
|
||||
|
||||
Operations may reference ids created earlier in the same batch.
|
||||
|
||||
**Options:**
|
||||
- `meta?`: `Record<string, unknown>` — transaction metadata, recorded durably in the transaction log (audit fields: author, reason, request id)
|
||||
- `ifAtGeneration?`: `number` — whole-store compare-and-swap; commits only if the store is still at this generation
|
||||
|
||||
**Returns:** `Promise<Db>` — pinned at the freshly committed generation, carrying a `receipt`.
|
||||
|
||||
**Throws:**
|
||||
- `GenerationConflictError` — `ifAtGeneration` did not match (nothing staged, generation unchanged)
|
||||
- `RevisionConflictError` — an `ifRev` did not match (whole batch rejected)
|
||||
|
||||
---
|
||||
|
||||
### `asOf(target)` → `Promise<Db>`
|
||||
|
||||
Open an immutable view of **past** state:
|
||||
|
||||
```typescript
|
||||
const atGen = await brain.asOf(1041) // generation number
|
||||
const lastWeek = await brain.asOf(new Date(Date.now() - 7 * 86_400_000)) // wall-clock
|
||||
const fromSnapshot = await brain.asOf('/backups/2026-06-01') // snapshot directory
|
||||
```
|
||||
|
||||
- **`number`** — pins that generation; reads resolve through the immutable record layer.
|
||||
- **`Date`** — resolved via the transaction log to the newest generation committed at or before it.
|
||||
- **`string`** — a snapshot directory from `db.persist()`, opened as a self-contained read-only store (equivalent to `Brainy.load()`).
|
||||
|
||||
Historical views serve the **full query surface**. Metadata-level reads are
|
||||
free; the first index-accelerated query (semantic search, traversal,
|
||||
cursors, aggregation) builds an in-memory index materialization — O(n at
|
||||
that generation), once per `Db`, freed on `release()`.
|
||||
|
||||
**Throws:** `GenerationCompactedError` when the generation's records were reclaimed by `compactHistory()`.
|
||||
|
||||
**History granularity:** only `transact()` batches produce historical
|
||||
records; single-operation writes advance the clock but stay visible through
|
||||
earlier pins. See the [consistency model](../concepts/consistency-model.md).
|
||||
|
||||
---
|
||||
|
||||
### `transactionLog(options?)` → `Promise<TxLogEntry[]>`
|
||||
|
||||
Read the reified transaction log — one entry per committed `transact()`
|
||||
batch, newest first: `{ generation, timestamp, meta? }`.
|
||||
|
||||
```typescript
|
||||
const [latest] = await brain.transactionLog({ limit: 1 })
|
||||
latest.meta // { author: 'order-service', requestId: 'req-9f2' }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `commit(options?)` → `Promise<string>`
|
||||
### `compactHistory(options?)` → `Promise<CompactHistoryResult>`
|
||||
|
||||
Create a commit snapshot.
|
||||
Reclaim historical record-sets that no retention rule and no live `Db` pin
|
||||
protects. Pinned reads stay correct across compaction, always.
|
||||
|
||||
```typescript
|
||||
const commitId = await brain.commit({
|
||||
message: 'Add new features',
|
||||
author: 'dev@example.com',
|
||||
metadata: { ticket: 'PROJ-123' }
|
||||
await brain.compactHistory({
|
||||
retainGenerations: 100, // keep the 100 most recent commits
|
||||
retainMs: 7 * 24 * 60 * 60 * 1000 // and everything from the last 7 days
|
||||
})
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `message?`: `string` - Commit message
|
||||
- `author?`: `string` - Author email
|
||||
- `metadata?`: `object` - Additional commit metadata
|
||||
|
||||
**Returns:** `Promise<string>` - Commit ID
|
||||
**Returns:** `{ removedGenerations, horizon }` — `asOf()` below the horizon throws `GenerationCompactedError`.
|
||||
|
||||
---
|
||||
|
||||
### `restore(path, { confirm: true })` → `Promise<void>`
|
||||
|
||||
### `deleteBranch(branch)` → `Promise<void>`
|
||||
|
||||
Delete a branch (cannot delete 'main').
|
||||
Replace the store's **entire** state from a snapshot directory. Destructive
|
||||
— requires `{ confirm: true }`. All indexes are rebuilt; the generation
|
||||
counter is floored so observed generation numbers are never reissued; live
|
||||
pins do not survive.
|
||||
|
||||
```typescript
|
||||
await brain.deleteBranch('old-experiment')
|
||||
await brain.restore('/backups/2026-06-01', { confirm: true })
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `getHistory(options?)` → `Promise<Commit[]>`
|
||||
### `Brainy.load(path)` → `Promise<Db>` (static)
|
||||
|
||||
Get commit history.
|
||||
Open a persisted snapshot as a self-contained **read-only** store with the
|
||||
full query surface, including vector search. Releasing the returned `Db`
|
||||
closes the underlying instance.
|
||||
|
||||
```typescript
|
||||
const history = await brain.getHistory({
|
||||
branch: 'main',
|
||||
limit: 10
|
||||
})
|
||||
const db = await Brainy.load('/backups/2026-06-01')
|
||||
const hits = await db.search('quarterly invoices')
|
||||
await db.release()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `asOf(commitId, options?)` → `Promise<Brainy>`
|
||||
### The `Db` value
|
||||
|
||||
Create a read-only snapshot at a specific commit for time-travel queries.
|
||||
Every `Db` is pinned at one generation and serves the full query surface at
|
||||
exactly that state.
|
||||
|
||||
**Properties:**
|
||||
|
||||
| Property | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `generation` | `number` | The pinned generation |
|
||||
| `timestamp` | `number` | Pin time (`now()`), commit time (`transact()`), or resolved commit time (`asOf()`) |
|
||||
| `receipt` | `TransactReceipt?` | Present only on `transact()` results |
|
||||
| `speculative` | `boolean` | Whether this view carries a `with()` overlay |
|
||||
| `released` | `boolean` | Whether `release()` has been called |
|
||||
|
||||
**Methods:**
|
||||
|
||||
```typescript
|
||||
// Get commit ID from history
|
||||
const commits = await brain.getHistory({ limit: 1 })
|
||||
const commitId = commits[0].id
|
||||
|
||||
// Create snapshot (lazy-loading, no eager data loading)
|
||||
const snapshot = await brain.asOf(commitId, {
|
||||
cacheSize: 10000 // LRU cache size (default: 10000)
|
||||
})
|
||||
|
||||
// Query historical state - full Triple Intelligence works!
|
||||
const results = await snapshot.find({
|
||||
query: 'AI research',
|
||||
where: { category: 'technology' }
|
||||
})
|
||||
|
||||
// Get historical relationships
|
||||
const related = await snapshot.getRelated(entityId, { depth: 2 })
|
||||
|
||||
// MUST close when done to free memory
|
||||
await snapshot.close()
|
||||
await db.get(id) // entity as of this generation
|
||||
await db.find({ where: { status: 'open' } }) // full find() surface
|
||||
await db.search('unpaid invoices') // semantic search as of this generation
|
||||
await db.related(entityId) // relationships as of this generation
|
||||
await db.since(olderDb) // ids changed between two views
|
||||
const whatIf = await db.with(ops) // speculative in-memory overlay
|
||||
await db.persist('/backups/today') // self-contained hard-link snapshot
|
||||
await db.release() // unpin + free cached materialization
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `commitId`: `string` - Commit hash to snapshot from
|
||||
- `options?`: `object`
|
||||
- `cacheSize?`: `number` - LRU cache size for lazy-loading (default: 10000)
|
||||
|
||||
**Returns:** `Promise<Brainy>` - Read-only Brainy instance with historical state
|
||||
|
||||
**Features:**
|
||||
- **Lazy-Loading** - Loads entities on-demand, not eagerly
|
||||
- **Bounded Memory** - LRU cache prevents memory bloat
|
||||
- **Full Query Support** - All find(), getRelated(), etc. work on historical data
|
||||
- **Read-Only** - Prevents accidental modifications to history
|
||||
|
||||
**Important:** Always call `snapshot.close()` when done to release resources.
|
||||
|
||||
---
|
||||
|
||||
## Entity Versioning
|
||||
|
||||
Git-style versioning for individual entities with content-addressable storage.
|
||||
|
||||
### Overview
|
||||
|
||||
Entity Versioning provides time-travel and history tracking for individual entities:
|
||||
|
||||
- **Content-Addressable Storage** - Deduplication via SHA-256 hashing
|
||||
- **Zero-Config** - Lazy initialization, uses existing indexes
|
||||
- **Branch-Isolated** - Versions isolated per branch
|
||||
- **Selective Auto-Versioning** - Optional augmentation for automatic version creation
|
||||
- **Production-Scale** - Designed for billions of entities
|
||||
- **VFS File Support** - Full versioning for VFS files with actual blob content
|
||||
|
||||
---
|
||||
|
||||
### `versions.save(entityId, options?)` → `Promise<EntityVersion>`
|
||||
|
||||
Save a new version of an entity.
|
||||
|
||||
```typescript
|
||||
// Save version with tag
|
||||
const version = await brain.versions.save('user-123', {
|
||||
tag: 'v1.0',
|
||||
description: 'Initial user profile',
|
||||
metadata: { author: 'dev@example.com' }
|
||||
})
|
||||
|
||||
console.log(version.version) // 1
|
||||
console.log(version.contentHash) // SHA-256 hash
|
||||
console.log(version.createdAt) // Timestamp
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `entityId`: `string` - Entity ID to version
|
||||
- `options?`: `object`
|
||||
- `tag?`: `string` - Version tag (e.g., 'v1.0', 'beta')
|
||||
- `description?`: `string` - Version description
|
||||
- `metadata?`: `object` - Additional version metadata
|
||||
|
||||
**Returns:** `Promise<EntityVersion>` - Created version
|
||||
|
||||
**Features:**
|
||||
- Automatic deduplication (identical content = same version)
|
||||
- Sequential version numbering (1, 2, 3, ...)
|
||||
- Content-addressable storage (SHA-256)
|
||||
|
||||
---
|
||||
|
||||
### `versions.list(entityId, options?)` → `Promise<EntityVersion[]>`
|
||||
|
||||
List all versions of an entity.
|
||||
|
||||
```typescript
|
||||
const versions = await brain.versions.list('user-123', {
|
||||
limit: 10,
|
||||
offset: 0
|
||||
})
|
||||
|
||||
versions.forEach(v => {
|
||||
console.log(`Version ${v.version}: ${v.tag} - ${v.description}`)
|
||||
})
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `entityId`: `string` - Entity ID
|
||||
- `options?`: `object`
|
||||
- `limit?`: `number` - Max versions to return
|
||||
- `offset?`: `number` - Skip versions
|
||||
|
||||
**Returns:** `Promise<EntityVersion[]>` - Versions (newest first)
|
||||
|
||||
---
|
||||
|
||||
### `versions.restore(entityId, versionOrTag)` → `Promise<void>`
|
||||
|
||||
Restore entity to a previous version.
|
||||
|
||||
```typescript
|
||||
// Restore by version number
|
||||
await brain.versions.restore('user-123', 1)
|
||||
|
||||
// Restore by tag
|
||||
await brain.versions.restore('user-123', 'beta')
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `entityId`: `string` - Entity ID
|
||||
- `versionOrTag`: `number | string` - Version number or tag
|
||||
|
||||
---
|
||||
|
||||
### `versions.compare(entityId, version1, version2)` → `Promise<VersionDiff>`
|
||||
|
||||
Compare two versions.
|
||||
|
||||
```typescript
|
||||
const diff = await brain.versions.compare('user-123', 1, 2)
|
||||
|
||||
console.log(diff.totalChanges) // Total changes
|
||||
console.log(diff.modified) // Modified fields
|
||||
console.log(diff.added) // Added fields
|
||||
console.log(diff.removed) // Removed fields
|
||||
|
||||
// Check specific changes
|
||||
const nameChange = diff.modified.find(c => c.path === 'metadata.name')
|
||||
console.log(`${nameChange.oldValue} → ${nameChange.newValue}`)
|
||||
```
|
||||
|
||||
**Returns:** `Promise<VersionDiff>` - Detailed diff with field-level changes
|
||||
|
||||
---
|
||||
|
||||
### `versions.getContent(entityId, versionOrTag)` → `Promise<EntitySnapshot>`
|
||||
|
||||
Get version content without restoring.
|
||||
|
||||
```typescript
|
||||
// View old version without changing current state
|
||||
const v1Content = await brain.versions.getContent('user-123', 1)
|
||||
console.log(v1Content.metadata.name) // Old name
|
||||
|
||||
// Current state unchanged
|
||||
const current = await brain.get('user-123')
|
||||
console.log(current.metadata.name) // Current name
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `versions.undo(entityId)` → `Promise<void>`
|
||||
|
||||
Undo to previous version (shorthand for restore to latest-1).
|
||||
|
||||
```typescript
|
||||
// Make a bad change
|
||||
await brain.update('user-123', { status: 'deleted' })
|
||||
|
||||
// Undo immediately
|
||||
await brain.versions.undo('user-123')
|
||||
```
|
||||
|
||||
**Alias:** `versions.revert(entityId)`
|
||||
|
||||
---
|
||||
|
||||
### `versions.prune(entityId, options)` → `Promise<PruneResult>`
|
||||
|
||||
Clean up old versions.
|
||||
|
||||
```typescript
|
||||
const result = await brain.versions.prune('user-123', {
|
||||
keepRecent: 10, // Keep 10 most recent
|
||||
keepTagged: true, // Always keep tagged versions
|
||||
olderThan: Date.now() - 30 * 24 * 60 * 60 * 1000 // Older than 30 days
|
||||
})
|
||||
|
||||
console.log(`Deleted ${result.deleted}, kept ${result.kept}`)
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `keepRecent?`: `number` - Keep N most recent versions
|
||||
- `keepTagged?`: `boolean` - Always keep tagged versions (default: true)
|
||||
- `olderThan?`: `number` - Only prune versions older than timestamp
|
||||
|
||||
---
|
||||
|
||||
### `versions.getLatest(entityId)` → `Promise<EntityVersion | null>`
|
||||
|
||||
Get latest version.
|
||||
|
||||
```typescript
|
||||
const latest = await brain.versions.getLatest('user-123')
|
||||
if (latest) {
|
||||
console.log(`Latest: v${latest.version} (${latest.tag})`)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `versions.getVersionByTag(entityId, tag)` → `Promise<EntityVersion | null>`
|
||||
|
||||
Get version by tag.
|
||||
|
||||
```typescript
|
||||
const beta = await brain.versions.getVersionByTag('user-123', 'beta')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `versions.count(entityId)` → `Promise<number>`
|
||||
|
||||
Count versions for an entity.
|
||||
|
||||
```typescript
|
||||
const count = await brain.versions.count('user-123')
|
||||
console.log(`${count} versions saved`)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `versions.hasVersions(entityId)` → `Promise<boolean>`
|
||||
|
||||
Check if entity has versions.
|
||||
|
||||
```typescript
|
||||
if (await brain.versions.hasVersions('user-123')) {
|
||||
console.log('Entity has version history')
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Auto-Versioning Augmentation
|
||||
|
||||
Automatically create versions on entity updates.
|
||||
|
||||
```typescript
|
||||
import { VersioningAugmentation } from '@soulcraft/brainy'
|
||||
|
||||
// Configure auto-versioning
|
||||
const versioning = new VersioningAugmentation({
|
||||
enabled: true,
|
||||
onUpdate: true, // Version on update()
|
||||
onDelete: false, // Don't version on delete
|
||||
entities: ['user-*'], // Only version users
|
||||
excludeEntities: ['temp-*'],
|
||||
excludeTypes: ['temporary'],
|
||||
keepRecent: 50, // Auto-prune old versions
|
||||
keepTagged: true
|
||||
})
|
||||
|
||||
// Apply augmentation
|
||||
brain.augment(versioning)
|
||||
|
||||
// Now updates auto-create versions
|
||||
await brain.update('user-123', { name: 'New Name' })
|
||||
|
||||
// Version automatically created!
|
||||
const versions = await brain.versions.list('user-123')
|
||||
console.log(`Auto-created version: ${versions[0].version}`)
|
||||
```
|
||||
|
||||
**Configuration:**
|
||||
- `enabled`: `boolean` - Enable/disable augmentation
|
||||
- `onUpdate`: `boolean` - Version on entity updates
|
||||
- `onDelete`: `boolean` - Version before deletion
|
||||
- `entities`: `string[]` - Entity ID patterns (glob-style)
|
||||
- `excludeEntities`: `string[]` - Exclusion patterns
|
||||
- `types`: `string[]` - Entity types to version
|
||||
- `excludeTypes`: `string[]` - Types to exclude
|
||||
- `keepRecent`: `number` - Auto-prune to keep N versions
|
||||
- `keepTagged`: `boolean` - Always keep tagged versions
|
||||
|
||||
**Pattern Matching:**
|
||||
- `['*']` - All entities
|
||||
- `['user-*']` - All IDs starting with "user-"
|
||||
- `['*-prod']` - All IDs ending with "-prod"
|
||||
- `['user-*', 'account-*']` - Multiple patterns
|
||||
|
||||
---
|
||||
|
||||
### Branch Isolation
|
||||
|
||||
Versions are isolated per branch.
|
||||
|
||||
```typescript
|
||||
// Save version on main
|
||||
await brain.versions.save('doc-1', { tag: 'main-v1' })
|
||||
|
||||
// Fork and create version
|
||||
const feature = await brain.fork('feature')
|
||||
await feature.update('doc-1', { content: 'Feature update' })
|
||||
await feature.versions.save('doc-1', { tag: 'feature-v1' })
|
||||
|
||||
// Versions are isolated
|
||||
const mainVersions = await brain.versions.list('doc-1')
|
||||
const featureVersions = await feature.versions.list('doc-1')
|
||||
|
||||
console.log(mainVersions.length !== featureVersions.length) // true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Architecture
|
||||
|
||||
**Content-Addressable Storage:**
|
||||
- SHA-256 hashing for deduplication
|
||||
- Identical content = single storage blob
|
||||
- Efficient for entities with few changes
|
||||
|
||||
**Metadata Indexing:**
|
||||
- Leverages existing MetadataIndexManager
|
||||
- Fast lookups by entity ID
|
||||
- Version number indexing
|
||||
|
||||
**Storage Structure:**
|
||||
```
|
||||
_version:{entityId}:{versionNum}:{branch} // Version metadata
|
||||
_version_blob:{contentHash} // Content blob (deduplicated)
|
||||
```
|
||||
|
||||
**Performance:**
|
||||
- Version save: O(1) if duplicate, O(log N) for index update
|
||||
- Version list: O(K) where K = version count
|
||||
- Version restore: O(log N) lookup + O(1) restore
|
||||
- Pruning: O(K) where K = versions pruned
|
||||
|
||||
---
|
||||
|
||||
### Examples
|
||||
|
||||
#### Basic Versioning Workflow
|
||||
|
||||
```typescript
|
||||
// Create entity
|
||||
await brain.add({
|
||||
data: 'User profile',
|
||||
id: 'user-123',
|
||||
type: 'user',
|
||||
metadata: { name: 'Alice', email: 'alice@example.com' }
|
||||
})
|
||||
|
||||
// Save v1
|
||||
await brain.versions.save('user-123', { tag: 'v1.0' })
|
||||
|
||||
// Make changes
|
||||
await brain.update('user-123', { name: 'Alice Smith' })
|
||||
|
||||
// Save v2
|
||||
await brain.versions.save('user-123', { tag: 'v2.0' })
|
||||
|
||||
// Compare versions
|
||||
const diff = await brain.versions.compare('user-123', 1, 2)
|
||||
|
||||
// Restore to v1 if needed
|
||||
await brain.versions.restore('user-123', 'v1.0')
|
||||
```
|
||||
|
||||
#### Release Management
|
||||
|
||||
```typescript
|
||||
// Development workflow
|
||||
await brain.update('app-config', { version: '1.0.0-alpha' })
|
||||
await brain.versions.save('app-config', { tag: 'alpha' })
|
||||
|
||||
await brain.update('app-config', { version: '1.0.0-beta' })
|
||||
await brain.versions.save('app-config', { tag: 'beta' })
|
||||
|
||||
await brain.update('app-config', { version: '1.0.0' })
|
||||
await brain.versions.save('app-config', { tag: 'release' })
|
||||
|
||||
// Rollback to beta if issues found
|
||||
await brain.versions.restore('app-config', 'beta')
|
||||
```
|
||||
|
||||
#### Audit Trail
|
||||
|
||||
```typescript
|
||||
// Track all changes
|
||||
const versioning = new VersioningAugmentation({
|
||||
enabled: true,
|
||||
onUpdate: true,
|
||||
entities: ['audit-*'],
|
||||
keepRecent: 100 // Keep 100 versions for audit
|
||||
})
|
||||
|
||||
brain.augment(versioning)
|
||||
|
||||
// All updates now tracked
|
||||
await brain.update('audit-record-1', { status: 'modified' })
|
||||
await brain.update('audit-record-1', { status: 'approved' })
|
||||
|
||||
// View complete history
|
||||
const versions = await brain.versions.list('audit-record-1')
|
||||
versions.forEach(v => {
|
||||
console.log(`${v.createdAt}: ${v.description}`)
|
||||
})
|
||||
```
|
||||
|
||||
#### VFS File Versioning
|
||||
|
||||
```typescript
|
||||
// VFS files can be versioned with actual blob content
|
||||
await brain.vfs.writeFile('/docs/readme.md', 'Version 1 content')
|
||||
|
||||
// Get the file's entity ID
|
||||
const stat = await brain.vfs.stat('/docs/readme.md')
|
||||
|
||||
// Save version 1
|
||||
await brain.versions.save(stat.entityId, { tag: 'v1', description: 'Initial draft' })
|
||||
|
||||
// Modify the file
|
||||
await brain.vfs.writeFile('/docs/readme.md', 'Version 2 - updated content')
|
||||
|
||||
// Save version 2
|
||||
await brain.versions.save(stat.entityId, { tag: 'v2', description: 'Updated docs' })
|
||||
|
||||
// Compare versions - content is DIFFERENT
|
||||
const v1 = await brain.versions.getContent(stat.entityId, 1)
|
||||
const v2 = await brain.versions.getContent(stat.entityId, 2)
|
||||
console.log(v1.data !== v2.data) // true
|
||||
|
||||
// Restore to v1 - writes content back to blob storage
|
||||
await brain.versions.restore(stat.entityId, 'v1')
|
||||
|
||||
// File is now back to v1
|
||||
const content = await brain.vfs.readFile('/docs/readme.md')
|
||||
console.log(content.toString()) // 'Version 1 content'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**[📖 Complete Versioning Guide →](../features/entity-versioning.md)**
|
||||
- **`with(ops)`** — applies `transact()`-style operations **in memory** on
|
||||
top of the view; nothing touches disk, the generation counter, or index
|
||||
providers. Overlay entities carry no embeddings, so index-accelerated
|
||||
queries and `persist()` on overlays throw `SpeculativeOverlayError`;
|
||||
`get()`, metadata-filter `find()`, and filter-based `related()` work
|
||||
fully. Commit the same ops with `transact()` for the full surface.
|
||||
- **`persist(path)`** — cuts an instant snapshot (hard links on filesystem
|
||||
storage; byte copies across devices; in-memory stores serialize to the
|
||||
same layout). Requires the view to still be the store's latest generation
|
||||
— otherwise `GenerationConflictError`.
|
||||
- **`release()`** — idempotent; after release every read throws. A
|
||||
`FinalizationRegistry` backstop releases leaked pins at GC, but explicit
|
||||
release is what makes `compactHistory()` deterministic.
|
||||
|
||||
### Db API errors
|
||||
|
||||
All exported from `@soulcraft/brainy`:
|
||||
|
||||
| Error | Thrown by | Meaning |
|
||||
|---|---|---|
|
||||
| `GenerationConflictError` | `transact({ ifAtGeneration })`, `db.persist()` | The store moved past the expected generation — re-read and retry |
|
||||
| `RevisionConflictError` | `update({ ifRev })`, `transact()` update ops | Per-entity revision moved — see [optimistic concurrency](../guides/optimistic-concurrency.md) |
|
||||
| `GenerationCompactedError` | `asOf()` | The requested generation's records were reclaimed — persist what you must keep |
|
||||
| `SpeculativeOverlayError` | index-accelerated reads / `persist()` on `with()` overlays | Honest boundary: overlay entities carry no embeddings |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -1759,8 +1407,6 @@ await brain.import('https://api.example.com/data.json')
|
|||
|
||||
**Returns:** `Promise<ImportResult>` - Import statistics
|
||||
|
||||
**Note:** Import always uses the current branch.
|
||||
|
||||
**[📖 Complete Import Guide →](../guides/import-anything.md)**
|
||||
|
||||
---
|
||||
|
|
@ -1771,12 +1417,15 @@ await brain.import('https://api.example.com/data.json')
|
|||
// Export to file
|
||||
await brain.export('/path/to/backup.brainy')
|
||||
|
||||
// Create instant snapshot using COW fork
|
||||
await brain.fork('backup-2025-01-19')
|
||||
// Instant hard-link snapshot via the Db API
|
||||
const pin = brain.now()
|
||||
await pin.persist('/backups/2026-06-11')
|
||||
await pin.release()
|
||||
|
||||
// Time-travel to specific commit
|
||||
const snapshot = await brain.asOf(commitId)
|
||||
// Time-travel to a past generation or timestamp
|
||||
const snapshot = await brain.asOf(new Date('2026-06-01'))
|
||||
const entities = await snapshot.find({ limit: 100 })
|
||||
await snapshot.release()
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -1819,7 +1468,7 @@ await brain.init() // Required! VFS auto-initialized
|
|||
|
||||
## Storage Adapters
|
||||
|
||||
Brainy 8.0 ships two adapters — both support **copy-on-write branching**.
|
||||
Brainy 8.0 ships two adapters — both support the full Db API (generational history, snapshots, restore).
|
||||
|
||||
### Memory (Default for Tests)
|
||||
|
||||
|
|
@ -2346,26 +1995,23 @@ const results = await brain.find({
|
|||
|
||||
---
|
||||
|
||||
### Git-Style Workflow
|
||||
### Database-as-a-Value Workflow
|
||||
|
||||
```typescript
|
||||
// Fork for experimentation
|
||||
const experiment = await brain.fork('test-migration')
|
||||
// Speculate: what would this change look like? (nothing touches disk)
|
||||
const base = brain.now()
|
||||
const whatIf = await base.with([
|
||||
{ op: 'add', type: NounType.Document, subtype: 'note', data: 'New feature' }
|
||||
])
|
||||
await whatIf.find({ where: { draft: true } })
|
||||
await whatIf.release()
|
||||
await base.release()
|
||||
|
||||
// Make changes in isolation
|
||||
await experiment.add({
|
||||
data: 'New feature',
|
||||
type: NounType.Document
|
||||
})
|
||||
|
||||
// Commit your work
|
||||
await experiment.commit({
|
||||
message: 'Add new feature',
|
||||
author: 'dev@example.com'
|
||||
})
|
||||
|
||||
// Switch to experimental branch to make it active
|
||||
await brain.checkout('test-migration')
|
||||
// Commit it for real — one atomic generation, with audit metadata
|
||||
await brain.transact(
|
||||
[{ op: 'add', type: NounType.Document, subtype: 'note', data: 'New feature' }],
|
||||
{ meta: { author: 'dev@example.com', message: 'Add new feature' } }
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -2483,22 +2129,17 @@ For the full taxonomy with all 169 types and their descriptions, see:
|
|||
|
||||
## Key Features
|
||||
|
||||
- ✅ **Entity Versioning** - Git-style versioning for individual entities
|
||||
- ✅ **Content-Addressable Storage** - SHA-256 deduplication for versions
|
||||
- ✅ **Auto-Versioning Augmentation** - Automatic version creation on updates
|
||||
- ✅ **Branch-Isolated Versions** - Versions isolated per branch
|
||||
- ✅ **VFS Entity Filtering** - All VFS entities now have `isVFSEntity: true` flag
|
||||
- ✅ **VFS Auto-Initialization** - No more separate `vfs.init()` calls
|
||||
- ✅ **Database as a Value** - `brain.now()` pins the whole store as an immutable `Db` in O(1)
|
||||
- ✅ **Atomic Transactions** - `brain.transact()` commits multi-write batches all-or-nothing
|
||||
- ✅ **Two-Level CAS** - per-entity `ifRev` and whole-store `ifAtGeneration`
|
||||
- ✅ **Time Travel** - `brain.asOf()` serves the full query surface at any reachable past generation
|
||||
- ✅ **Instant Snapshots** - `db.persist()` cuts hard-link snapshots; `Brainy.load()` opens them read-only
|
||||
- ✅ **Speculative Writes** - `db.with()` answers what-if questions purely in memory
|
||||
- ✅ **Reified Transaction Metadata** - audit fields recorded durably, readable via `transactionLog()`
|
||||
- ✅ **VFS Entity Filtering** - All VFS entities have the `isVFSEntity: true` flag
|
||||
- ✅ **VFS Auto-Initialization** - No separate `vfs.init()` calls
|
||||
- ✅ **VFS Property Access** - Use `brain.vfs.method()` instead of `brain.vfs().method()`
|
||||
- ✅ **Complete COW Support** - All 20 TypeAware methods use COW helpers
|
||||
- ✅ **Verified Import/Export** - Work correctly with current branch
|
||||
- ✅ **Instant Fork** - Snowflake-style copy-on-write (<100ms fork time)
|
||||
- ✅ **Git-Style Branching** - fork, commit, checkout, listBranches
|
||||
- ✅ **Full Branch Isolation** - Parent and fork fully isolated
|
||||
- ✅ **Read-Through Inheritance** - Forks see parent + own data
|
||||
- ✅ **Universal Storage Support** - Filesystem and memory adapters both support branching
|
||||
|
||||
**[📖 Complete Changes →](../../.strategy/v5.1.0-CHANGES.md)**
|
||||
- ✅ **Universal Storage Support** - Filesystem and memory adapters share one on-disk contract
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -2521,7 +2162,8 @@ For the full taxonomy with all 169 types and their descriptions, see:
|
|||
- **[VFS Quick Start](../vfs/QUICK_START.md)** - Complete VFS documentation
|
||||
- **[Import Anything Guide](../guides/import-anything.md)** - CSV, Excel, PDF, URL imports
|
||||
- **[Cloud Deployment](../deployment/CLOUD_DEPLOYMENT_GUIDE.md)** - Production deployment
|
||||
- **[Instant Fork](../features/instant-fork.md)** - Git-style branching guide
|
||||
- **[Consistency Model](../concepts/consistency-model.md)** - The guarantees behind the Db API
|
||||
- **[Snapshots & Time Travel](../guides/snapshots-and-time-travel.md)** - Backup, restore, what-if, audit recipes
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -2530,4 +2172,4 @@ For the full taxonomy with all 169 types and their descriptions, see:
|
|||
---
|
||||
|
||||
*Brainy - The Knowledge Operating System*
|
||||
*From prototype to planet-scale • Zero configuration • Triple Intelligence™ • Git-Style Branching*
|
||||
*From prototype to planet-scale • Zero configuration • Triple Intelligence™ • Database as a Value*
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue