David Snelling
48802ba385
Open Brainy's side of the API contract the accelerated engine published.
DECLARED: package.json carries "brainyContract": 1 and the engine states its
own via contractVersion() / BRAINY_CONTRACT_VERSION — two engines compare an
integer instead of probing prototypes, and a tool reads the package field
without importing the engine. Pinned so the two can never drift apart.
SERVED: hasAll, noneOf and excludes now work on the index path. The defect
underneath was worse than the reported divergence — the metadata index's
operator switch had NO DEFAULT CASE, so any operator without a case left the
field's match set at its initial [] and find() returned an empty page.
Documented, validator-accepted, matcher-implemented operators answering
silently wrong. hasAll intersects each element's posting set (an empty operand
is vacuously true of every row that has the field), noneOf complements their
union, excludes complements contains.
REFUSED BY NAME: startsWith, endsWith, matches and length raise
INVALID_QUERY naming the operator, the field and the reason. An equality/range
posting index cannot evaluate a substring, a pattern or an array length without
reading every row — which is the cost this path exists to avoid — so it refuses
rather than answering an empty page. Both engines now agree on all 25 tokens
and contract 1 has no remaining operator divergence. This is a visible change
for a consumer calling those four through find({ where }): an empty page
becomes a typed refusal.
EMITTED: scripts/emit-contract-manifest.mjs generates docs/api-contract.json
from the BUILT surface — prototype doors, exported error classes, the operator
sets read out of their single definitions, the field-addressing vocabulary, the
health verdicts. Nothing hand-maintained, so a diff between two manifests is a
diff between two engines. `--check` fails on a stale manifest, which makes the
announce-every-addition duty mechanical rather than remembered.
RATIFIED in docs/contract-1-ratification.md: the 41-of-57 required split with
the promise spelled out (a refusal is part of a door; deprecation is not
removal), the serving-withholding list confirmed exhaustive and identical, the
minor/major rule adopted with the announcement duty, the 30 storage seam
methods committed as supported surface until Stage 2, and a finding filed
against the spec — is / isNot / greaterEqual / lessEqual are listed there as
served aliases and have never existed in this engine, which throws
INVALID_QUERY on all four.
|
||
|---|---|---|
| .. | ||
| 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.