chore(8.0): final pre-RC1 sweep — API consistency, named errors, orphans, zero-cast codebase
This commit is contained in:
parent
970e08c466
commit
1f7e365a4e
237 changed files with 1951 additions and 49413 deletions
|
|
@ -97,7 +97,7 @@ On `brain.update(entity)`, the engine reverses the old entity's contribution and
|
|||
|
||||
### Delete Handling
|
||||
|
||||
On `brain.delete(id)`, the engine reverses the entity's contribution:
|
||||
On `brain.remove(id)`, the engine reverses the entity's contribution:
|
||||
|
||||
- `count` and `sum` are decremented
|
||||
- `min`/`max` may become stale (marked in `staleMinMax` for lazy recompute)
|
||||
|
|
|
|||
|
|
@ -1,359 +0,0 @@
|
|||
# 🔍 Brainy 2.0 Augmentation System Architecture Audit (REVISED)
|
||||
|
||||
**Author**: Senior Architecture Review
|
||||
**Date**: 2025-08-25
|
||||
**Status**: 🟡 **WORKING BUT NEEDS MARKETPLACE FEATURES**
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The augmentation system core execution is WORKING correctly through `AugmentationRegistry`. The system properly executes augmentations before/after operations. However, there's no discovery, installation, or marketplace integration for the brain-cloud registry vision.
|
||||
|
||||
---
|
||||
|
||||
## 🟢 What's Actually Working
|
||||
|
||||
### 1. Execution Mechanism ✅
|
||||
The `AugmentationRegistry` class properly implements:
|
||||
```typescript
|
||||
async execute<T>(operation: string, params: any, mainOperation: () => Promise<T>): Promise<T>
|
||||
```
|
||||
- Chains augmentations correctly
|
||||
- Respects timing (before/after/around)
|
||||
- Handles operation filtering
|
||||
- Works with all 27 augmentations
|
||||
|
||||
### 2. Registration System ✅
|
||||
```typescript
|
||||
brain.augmentations.register(augmentation)
|
||||
```
|
||||
- Two-phase initialization works (storage first)
|
||||
- Context injection works
|
||||
- Lifecycle management works
|
||||
|
||||
### 3. Clean Interface ✅
|
||||
- 100% of augmentations use `BrainyAugmentation`
|
||||
- `BaseAugmentation` provides solid foundation
|
||||
- Proper TypeScript types
|
||||
|
||||
### 4. Auto-Configuration ✅
|
||||
```typescript
|
||||
new Brainy({
|
||||
cache: true, // Auto-registers CacheAugmentation
|
||||
index: true, // Auto-registers IndexAugmentation
|
||||
storage: { type: 'filesystem', rootDirectory: './data' } // Auto-registers FileSystemStorageAugmentation
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🟡 Missing for Marketplace Vision
|
||||
|
||||
### 1. No Package Discovery
|
||||
**Current**: Manual registration only
|
||||
```typescript
|
||||
// Current (manual)
|
||||
import { NotionSynapse } from './my-custom-synapse'
|
||||
brain.augmentations.register(new NotionSynapse())
|
||||
|
||||
// Needed
|
||||
await brain.discover('notion') // Search npm/brain-cloud
|
||||
await brain.install('@soulcraft/notion-synapse')
|
||||
```
|
||||
|
||||
### 2. No Installation Mechanism
|
||||
**Current**: Must be bundled at build time
|
||||
**Needed**: Dynamic installation
|
||||
```typescript
|
||||
interface AugmentationMarketplace {
|
||||
search(query: string): Promise<Package[]>
|
||||
install(packageId: string): Promise<void>
|
||||
uninstall(packageId: string): Promise<void>
|
||||
listInstalled(): Promise<Package[]>
|
||||
checkUpdates(): Promise<Update[]>
|
||||
}
|
||||
```
|
||||
|
||||
### 3. No Brain Cloud Registry Client
|
||||
**Current**: No registry concept
|
||||
**Needed**: Registry integration
|
||||
```typescript
|
||||
class BrainCloudRegistry {
|
||||
private apiUrl = 'https://api.soulcraft.com/brain-cloud'
|
||||
|
||||
async search(query: string): Promise<AugmentationPackage[]> {
|
||||
const response = await fetch(`${this.apiUrl}/augmentations/search?q=${query}`)
|
||||
return response.json()
|
||||
}
|
||||
|
||||
async getPackage(id: string): Promise<AugmentationPackage> {
|
||||
const response = await fetch(`${this.apiUrl}/augmentations/${id}`)
|
||||
return response.json()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. No License Management
|
||||
**Current**: All augmentations free/bundled
|
||||
**Needed**: License verification
|
||||
```typescript
|
||||
interface LicenseManager {
|
||||
verify(packageId: string, licenseKey: string): Promise<boolean>
|
||||
activate(packageId: string, licenseKey: string): Promise<void>
|
||||
deactivate(packageId: string): Promise<void>
|
||||
getStatus(packageId: string): Promise<LicenseStatus>
|
||||
}
|
||||
```
|
||||
|
||||
### 5. No Version Management
|
||||
**Current**: No versioning
|
||||
**Needed**: Semver support
|
||||
```typescript
|
||||
interface VersionManager {
|
||||
checkCompatibility(pkg: Package, brainyVersion: string): boolean
|
||||
resolveConflicts(packages: Package[]): Package[]
|
||||
upgrade(packageId: string, toVersion: string): Promise<void>
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Implementation Plan for Marketplace
|
||||
|
||||
### Phase 1: Local Package Discovery (1 week)
|
||||
```typescript
|
||||
class LocalPackageDiscovery {
|
||||
async discover(): Promise<Package[]> {
|
||||
// 1. Search node_modules for brainy augmentations
|
||||
const packages = await glob('node_modules/@*/package.json')
|
||||
|
||||
// 2. Filter for brainy augmentations
|
||||
return packages.filter(pkg => pkg.brainy?.type === 'augmentation')
|
||||
}
|
||||
|
||||
async load(packageId: string): Promise<BrainyAugmentation> {
|
||||
// Dynamic import
|
||||
const module = await import(packageId)
|
||||
return new module.default()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 2: NPM Integration (1 week)
|
||||
```typescript
|
||||
class NPMRegistry {
|
||||
async search(query: string): Promise<Package[]> {
|
||||
// Search npm for packages with brainy keyword
|
||||
const response = await fetch(
|
||||
`https://registry.npmjs.org/-/v1/search?text=${query}+keywords:brainy-augmentation`
|
||||
)
|
||||
return response.json()
|
||||
}
|
||||
|
||||
async install(packageId: string): Promise<void> {
|
||||
// Use npm programmatically
|
||||
await exec(`npm install ${packageId}`)
|
||||
|
||||
// Auto-register after install
|
||||
const aug = await this.load(packageId)
|
||||
this.brain.augmentations.register(aug)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: Brain Cloud Registry (2 weeks)
|
||||
```typescript
|
||||
class BrainCloudMarketplace {
|
||||
private registry = new BrainCloudRegistry()
|
||||
private licenses = new LicenseManager()
|
||||
private installer = new AugmentationInstaller()
|
||||
|
||||
async browse(category?: string): Promise<MarketplaceListing[]> {
|
||||
const packages = await this.registry.list(category)
|
||||
|
||||
return packages.map(pkg => ({
|
||||
...pkg,
|
||||
installed: this.isInstalled(pkg.id),
|
||||
licensed: this.isLicensed(pkg.id),
|
||||
updates: this.hasUpdates(pkg.id)
|
||||
}))
|
||||
}
|
||||
|
||||
async purchase(packageId: string): Promise<void> {
|
||||
// 1. Process payment
|
||||
const license = await this.processPayment(packageId)
|
||||
|
||||
// 2. Activate license
|
||||
await this.licenses.activate(packageId, license)
|
||||
|
||||
// 3. Install package
|
||||
await this.install(packageId)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 4: Developer Tools (1 week)
|
||||
```typescript
|
||||
// CLI for augmentation development
|
||||
class AugmentationCLI {
|
||||
async create(name: string): Promise<void> {
|
||||
// Scaffold new augmentation project
|
||||
await this.scaffold(name, 'augmentation-template')
|
||||
}
|
||||
|
||||
async test(path: string): Promise<void> {
|
||||
// Test augmentation locally
|
||||
const aug = await this.load(path)
|
||||
await this.runTests(aug)
|
||||
}
|
||||
|
||||
async publish(path: string): Promise<void> {
|
||||
// Publish to brain-cloud
|
||||
const pkg = await this.package(path)
|
||||
await this.registry.publish(pkg)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Recommended Architecture
|
||||
|
||||
### 1. Augmentation Package Structure
|
||||
```json
|
||||
{
|
||||
"name": "@soulcraft/notion-synapse",
|
||||
"version": "1.0.0",
|
||||
"main": "dist/index.js",
|
||||
"types": "dist/index.d.ts",
|
||||
"brainy": {
|
||||
"type": "augmentation",
|
||||
"class": "NotionSynapse",
|
||||
"timing": "after",
|
||||
"operations": ["addNoun", "updateNoun"],
|
||||
"priority": 20,
|
||||
"license": "premium",
|
||||
"price": 9.99,
|
||||
"compatibility": ">=2.0.0",
|
||||
"dependencies": []
|
||||
},
|
||||
"keywords": ["brainy-augmentation", "notion", "sync"]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Installation Flow
|
||||
```typescript
|
||||
// User flow
|
||||
await brain.marketplace.search('notion')
|
||||
// Returns: [@soulcraft/notion-synapse, @community/notion-sync, ...]
|
||||
|
||||
await brain.marketplace.install('@soulcraft/notion-synapse')
|
||||
// 1. Check license (prompt for purchase if needed)
|
||||
// 2. Check compatibility
|
||||
// 3. Install dependencies
|
||||
// 4. Download package
|
||||
// 5. Load augmentation
|
||||
// 6. Register with brain
|
||||
// 7. Initialize
|
||||
|
||||
// Now it's working!
|
||||
brain.augmentations.list()
|
||||
// [..., { name: '@soulcraft/notion-synapse', enabled: true }]
|
||||
```
|
||||
|
||||
### 3. Discovery UI
|
||||
```typescript
|
||||
// Web UI component
|
||||
<AugmentationMarketplace>
|
||||
<SearchBar />
|
||||
<Categories>
|
||||
<Category name="Storage" count={12} />
|
||||
<Category name="Sync" count={8} />
|
||||
<Category name="AI" count={15} />
|
||||
</Categories>
|
||||
<Results>
|
||||
<AugmentationCard
|
||||
name="Notion Synapse"
|
||||
author="Soulcraft"
|
||||
rating={4.8}
|
||||
installs={1200}
|
||||
price={9.99}
|
||||
onInstall={...}
|
||||
/>
|
||||
</Results>
|
||||
</AugmentationMarketplace>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Priority for 2.0 Release
|
||||
|
||||
### Must Have (Release Blockers)
|
||||
- ✅ Working execution (DONE)
|
||||
- ✅ Clean interface (DONE)
|
||||
- ✅ Documentation (DONE)
|
||||
- ⏳ Fix augmentationPipeline.ts removal
|
||||
- ⏳ Test all 27 augmentations work
|
||||
|
||||
### Nice to Have (2.0.x)
|
||||
- Local package discovery
|
||||
- NPM integration
|
||||
- Basic CLI tools
|
||||
|
||||
### Future (2.1+)
|
||||
- Brain Cloud Registry
|
||||
- License management
|
||||
- Payment processing
|
||||
- Marketplace UI
|
||||
- Developer portal
|
||||
|
||||
---
|
||||
|
||||
## 📊 Current State Assessment
|
||||
|
||||
| Component | Status | Notes |
|
||||
|-----------|--------|-------|
|
||||
| Core Execution | ✅ Working | AugmentationRegistry.execute() works |
|
||||
| Registration | ✅ Working | Manual registration works |
|
||||
| Auto-Config | ✅ Working | Cache, index, storage auto-register |
|
||||
| Lifecycle | ✅ Working | Init, execute, shutdown work |
|
||||
| Discovery | ❌ Missing | No package discovery |
|
||||
| Installation | ❌ Missing | No dynamic installation |
|
||||
| Marketplace | ❌ Missing | No registry client |
|
||||
| Licensing | ❌ Missing | No license management |
|
||||
| Versioning | ❌ Missing | No version checks |
|
||||
|
||||
---
|
||||
|
||||
## 💡 Recommendations
|
||||
|
||||
### For 2.0 Release
|
||||
1. **Ship with manual registration** - It works!
|
||||
2. **Document how to create augmentations** - Critical for adoption
|
||||
3. **Create 2-3 example augmentations** - Show the patterns
|
||||
4. **Add basic CLI for testing** - Help developers
|
||||
|
||||
### For 2.1 (Q1 2025)
|
||||
1. **Add NPM discovery** - Find installed augmentations
|
||||
2. **Dynamic loading** - Import augmentations at runtime
|
||||
3. **Basic marketplace API** - List available augmentations
|
||||
4. **Version checking** - Ensure compatibility
|
||||
|
||||
### For 3.0 (Q2 2025)
|
||||
1. **Full marketplace** - Browse, search, install
|
||||
2. **Payment integration** - Premium augmentations
|
||||
3. **Developer portal** - Publish augmentations
|
||||
4. **Enterprise features** - Private registries
|
||||
|
||||
---
|
||||
|
||||
## ✅ Good News Summary
|
||||
|
||||
The augmentation system WORKS! The core architecture is solid:
|
||||
- Execution mechanism is correct
|
||||
- Registration works
|
||||
- Lifecycle management works
|
||||
- All 27 augmentations function properly
|
||||
|
||||
What's missing is the marketplace/discovery layer, which can be added incrementally without breaking the core system. The 2.0 release can ship with manual augmentation registration, and the marketplace features can be added in 2.1+.
|
||||
|
||||
**Recommendation: Ship 2.0 with current system, add marketplace in 2.1**
|
||||
|
|
@ -195,7 +195,7 @@ tx-log line is appended last (advisory). Crash recovery on open discards any
|
|||
|
||||
Two write classes share the generation clock:
|
||||
|
||||
- **Single-operation writes** (`add`/`update`/`delete`/`relate` outside
|
||||
- **Single-operation writes** (`add`/`update`/`remove`/`relate` outside
|
||||
`transact()`) bump `generation.json` so watermarks and `_rev` CAS stay sound,
|
||||
but write **no** history — they are not visible to `db.since()` and remain
|
||||
visible through earlier pins.
|
||||
|
|
|
|||
|
|
@ -239,37 +239,30 @@ await brain.storage.withLock('resource-id', async () => {
|
|||
|
||||
## Migration and Backup
|
||||
|
||||
### Export Data
|
||||
Backup and restore go through the Db API — see
|
||||
[Snapshots & Time Travel](../guides/snapshots-and-time-travel.md) for the full
|
||||
recipe book.
|
||||
|
||||
### Snapshot (backup)
|
||||
```typescript
|
||||
// Export entire database
|
||||
const backup = await brain.export({
|
||||
format: 'json',
|
||||
includeVectors: true,
|
||||
includeIndexes: false
|
||||
})
|
||||
// Instant, self-contained snapshot (hard links on filesystem storage)
|
||||
const db = brain.now()
|
||||
await db.persist('/backups/2026-06-11')
|
||||
await db.release()
|
||||
```
|
||||
|
||||
### Import Data
|
||||
### Restore
|
||||
```typescript
|
||||
// Import from backup
|
||||
await brain.import(backup, {
|
||||
mode: 'merge', // or 'replace'
|
||||
validateSchema: true
|
||||
})
|
||||
// Replace the store's entire state from a snapshot (destructive — confirm required)
|
||||
await brain.restore('/backups/2026-06-11', { confirm: true })
|
||||
```
|
||||
|
||||
### Storage Migration
|
||||
### Move to a new directory
|
||||
```typescript
|
||||
// Migrate between storage types
|
||||
const oldBrain = new Brainy({ storage: { type: 'filesystem', rootDirectory: './old' } })
|
||||
const newBrain = new Brainy({ storage: { type: 'filesystem', rootDirectory: './new' } })
|
||||
|
||||
await oldBrain.init()
|
||||
await newBrain.init()
|
||||
|
||||
// Transfer all data
|
||||
const data = await oldBrain.export()
|
||||
await newBrain.import(data)
|
||||
// A snapshot directory is a complete store: restore it into a fresh brain
|
||||
const brain = new Brainy({ storage: { type: 'filesystem', rootDirectory: './new' } })
|
||||
await brain.init()
|
||||
await brain.restore('/backups/2026-06-11', { confirm: true })
|
||||
```
|
||||
|
||||
## Performance Tuning
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
---
|
||||
title: Zero Configuration
|
||||
slug: concepts/zero-config
|
||||
public: true
|
||||
public: false
|
||||
category: concepts
|
||||
template: concept
|
||||
order: 3
|
||||
description: Brainy auto-detects storage, initializes embeddings, and builds indexes — no configuration required. Works in Node.js, Bun, OPFS, and cloud environments.
|
||||
description: Brainy auto-detects storage, initializes embeddings, and builds indexes — no configuration required. Works in Node.js and Bun (server-only since 8.0).
|
||||
next:
|
||||
- getting-started/installation
|
||||
- guides/storage-adapters
|
||||
|
|
@ -13,7 +13,13 @@ next:
|
|||
|
||||
# Zero Configuration & Auto-Adaptation
|
||||
|
||||
> **Current Status**: Basic zero-config is fully functional. Advanced auto-adaptation features are in development.
|
||||
> **Status (8.0):** This document predates Brainy 8.0 and needs a rewrite before
|
||||
> republication. Large parts describe storage backends and environments that 8.0
|
||||
> removed (browser/OPFS/IndexedDB, edge KV, S3) or features that were never built
|
||||
> (model auto-selection, workload detection). Brainy 8.0 is server-only (Node.js/Bun)
|
||||
> with two storage adapters: `memory` and `filesystem` — see
|
||||
> [Storage Adapters](../concepts/storage-adapters.md) for the accurate story.
|
||||
> Basic zero-config (`new Brainy()` with auto-selected storage) works as described.
|
||||
|
||||
## Overview
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue