David Snelling
72c8ee6acd
The 10.4.11 flush single-flight work added `startFlushLeader` and `promoteQueuedFlush` as TypeScript `private` methods. `private` is erased at compile time, so both still land on the prototype — and the contract manifest emitter reads the surface the BUILD exposes, skipping only names that start with an underscore. On the next regeneration both would have been emitted as contract doors, obliging every engine implementing contract 1 to provide the flush gate's own bookkeeping. A door is a promise; these are internals. Converted to ECMAScript-private (`#`), which keeps them off the prototype entirely, and the reason is recorded on both so the next internal is not written as `private` by habit. `_runFlush` — the flush body itself — was already safe by the emitter's underscore rule. Verified: `npm run build && node scripts/emit-contract-manifest.mjs` then `--check` green at 302 doors, with neither name present. TWO MANIFEST NOTES, both deliberate and neither hidden: 1. The regenerated manifest gains `MetadataArrayTooLargeError`. The emitter lists every `*Error` export from brainyError.js, and that class is the write door's refusal for an over-bound metadata array (this branch's array-bound commit). It is a real addition to the engine's error surface, so the manifest is right to carry it — flagged here because it is a contract-surface change that the cut should accept knowingly, not a side effect that slipped in. 2. `armIdleFlushTimer` and `kickBackgroundFlush` are TypeScript `private` in src and ARE already in the committed manifest as doors — the same leak, one release older. They are left exactly as they are: removing a name the manifest already publishes is a contract deletion, not a hygiene fix, and it belongs to whoever owns contract 1 rather than to this branch. |
||
|---|---|---|
| .. | ||
| api | ||
| architecture | ||
| concepts | ||
| guides | ||
| operations | ||
| vfs | ||
| ADR-001-generational-mvcc.md | ||
| api-contract.json | ||
| BATCHING.md | ||
| DATA_MODEL.md | ||
| DEVELOPER_LEARNING_PATH.md | ||
| eli5.md | ||
| FIND_SYSTEM.md | ||
| MIGRATION-V3-TO-V4.md | ||
| neural-extraction.md | ||
| path-registry.md | ||
| performance-envelopes.md | ||
| PERFORMANCE.md | ||
| PLUGINS.md | ||
| PRODUCTION_SERVICE_ARCHITECTURE.md | ||
| QUERY_OPERATORS.md | ||
| README.md | ||
| RELEASE-GUIDE.md | ||
| SCALING.md | ||
| STAGE3-CANONICAL-TAXONOMY.md | ||
| transactions.md | ||
| troubleshooting.md | ||
| universal-display-augmentation.md | ||
Brainy Documentation
The multi-dimensional AI database with Triple Intelligence — vector search, graph traversal, and metadata filtering in one unified API.
Quick Start
import { Brainy, NounType, VerbType } from '@soulcraftlabs/brainy'
const brain = new Brainy()
await brain.init()
// Add entities — data is embedded for semantic search, metadata is indexed for filtering
const id = await brain.add({
data: 'Revolutionary AI Breakthrough',
type: NounType.Document,
metadata: { category: 'technology', rating: 4.8 }
})
// Search with Triple Intelligence
const results = await brain.find({
query: 'artificial intelligence', // Semantic search (on data)
where: { rating: { greaterThan: 4.0 } }, // Metadata filter
connected: { from: authorId, depth: 2 } // Graph traversal
})
Core Documentation
| Document | Description |
|---|---|
| API Reference | Complete API documentation — start here |
| Data Model | Entity structure, data vs metadata, storage fields |
| Query Operators | All BFO operators with examples and indexed/in-memory matrix |
| Find System | Natural language find() and hybrid search details |
| Consistency Model | The Db API guarantees — snapshot isolation, atomic transactions, time travel |
Architecture
| Document | Description |
|---|---|
| Architecture Overview | High-level system design |
| Triple Intelligence | Vector + Graph + Metadata unified query |
| Noun-Verb Taxonomy | 42 nouns + 127 verbs type system |
| Stage 3 Canonical Taxonomy | Complete type reference |
| Storage Architecture | Storage adapters and optimization |
| Index Architecture | Vector, Graph, and Metadata indexing |
| Zero Configuration | Auto-adapts to any environment |
Virtual Filesystem (VFS)
| Document | Description |
|---|---|
| VFS Quick Start | Get started in 30 seconds |
| VFS Core | Core concepts and architecture |
| VFS API Guide | Complete VFS API reference |
| Common Patterns | VFS usage patterns |
See vfs/ for the complete VFS documentation set.
Guides
| Document | Description |
|---|---|
| Import Anything | CSV, Excel, PDF, URL imports |
| Snapshots & Time Travel | Backups, restore, what-if analysis, audit trails |
| Natural Language | Query in plain English |
| Neural API | AI-powered features |
| Enterprise for Everyone | No limits, no tiers |
| Framework Integration | React, Vue, Angular, Svelte |
Storage & Deployment
| Document | Description |
|---|---|
| Storage Architecture | Filesystem and memory adapters, on-disk artifact layout, operator-layer backup |
| Capacity Planning | Scale to millions of entities |
Plugins
| Document | Description |
|---|---|
| Plugins | Plugin system overview — providers, plugins config, brain.use() |
Performance & Scaling
| Document | Description |
|---|---|
| Performance | Optimization techniques |
| Scaling | Scale to billions of entities |
| Batching | Batch operations guide |
Migration & Reference
| Document | Description |
|---|---|
| v3 to v4 Migration | Upgrade guide |
| Release Guide | How to release new versions |
| Production Architecture | Ops reference |
Internal
| Document | Description |
|---|---|
| Audit Report | Feature audit |
| Honest Status | Actual implementation status |
License
Brainy is MIT licensed. See LICENSE for details.