feat(8.0): API simplification — remove neural()/Db.search, one storage path key, integration→0
8.0 RC cleanup toward "one place per thing, zero-config, no deprecation":
- Remove the `brain.neural()` clustering namespace (ImprovedNeuralAPI + the dead
legacy NeuralAPI + the neural CLI + neural-only types). Similarity is `find({vector})`
/ `similar({to})`; attribute grouping is the aggregation `GROUP BY` engine. The separate
entity-extraction / smart-import feature (NeuralImport, NeuralEntityExtractor, SmartExtractor,
NaturalLanguageProcessor, `brain.extract()`/`brain.nlp()`) is kept.
- Remove `Db.search()`; `find()` is the one query verb (accepts a bare string or FindParams).
Fix the bundled MCP client, which called a non-existent `brain.search(query, limit)` →
now `find({ query, limit })`.
- Storage config: collapse to one canonical top-level `path` key. The pre-8.0 aliases
(`rootDirectory`, `options.*`, `fileSystemStorage.*`) are removed and now THROW with the
exact rename instead of silently defaulting to `./brainy-data` on upgrade. A single resolver
feeds createStorage, the 7.x→8.0 migration probe, and the plugin-factory handoff, so a native
storage provider resolves the identical root (no split-brain).
- Fix `similar({ threshold })`: the min-similarity filter was silently dropped; it is now
applied as a post-filter on `result.score` (the documented way to bound semantic results).
- Fix `vfs.rename()` on a directory: child path updates spread the entity vector into `update()`
and failed dimension validation; they are metadata-only updates now.
- Fix `vfs.move()`: copy+delete orphaned the content-addressed content blob (the destination
shared the source hash, then unlink removed it). `move()` now delegates to `rename()` — an
in-place path change that preserves the blob and the entity id, for files and directories.
- Fix streaming import: the bulk fast path never flushed mid-import nor signalled queryability.
Entity writes are now chunked by a progressive flush interval (100 → 1000 → 5000); each chunk
flushes and emits `progress.queryable`, so imported data is queryable during the import.
- Sweep all docs, comments, and JSDoc for the removed/changed APIs.
Integration suite: 49 files / 588 passed / 0 failed. Unit: 80 files / 1456 passed, no type errors.
This commit is contained in:
parent
0c4a51c24e
commit
606445cd61
74 changed files with 712 additions and 7470 deletions
|
|
@ -45,7 +45,7 @@ describe('Multi-process safety + read-only mode', () => {
|
|||
|
||||
describe('ReaderMode enforcement', () => {
|
||||
it('rejects every mutation when opened via openReadOnly()', async () => {
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', rootDirectory: dir } })
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', path: dir } })
|
||||
await writer.init()
|
||||
await writer.add({ data: 'seed entity', type: NounType.Concept })
|
||||
await writer.flush()
|
||||
|
|
@ -53,7 +53,7 @@ describe('Multi-process safety + read-only mode', () => {
|
|||
writer = null
|
||||
|
||||
reader = await Brainy.openReadOnly({
|
||||
storage: { type: 'filesystem', rootDirectory: dir }
|
||||
storage: { type: 'filesystem', path: dir }
|
||||
})
|
||||
|
||||
expect(reader.isReadOnly).toBe(true)
|
||||
|
|
@ -67,7 +67,7 @@ describe('Multi-process safety + read-only mode', () => {
|
|||
})
|
||||
|
||||
it('flush() and close() are safe to call in read-only mode', async () => {
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', rootDirectory: dir } })
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', path: dir } })
|
||||
await writer.init()
|
||||
await writer.add({ data: 'thing', type: NounType.Concept })
|
||||
await writer.flush()
|
||||
|
|
@ -75,7 +75,7 @@ describe('Multi-process safety + read-only mode', () => {
|
|||
writer = null
|
||||
|
||||
reader = await Brainy.openReadOnly({
|
||||
storage: { type: 'filesystem', rootDirectory: dir }
|
||||
storage: { type: 'filesystem', path: dir }
|
||||
})
|
||||
await expect(reader.flush()).resolves.toBeUndefined()
|
||||
await expect(reader.close()).resolves.toBeUndefined()
|
||||
|
|
@ -105,7 +105,7 @@ describe('Multi-process safety + read-only mode', () => {
|
|||
rootDir: dir
|
||||
}))
|
||||
|
||||
const blocked = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', rootDirectory: dir } })
|
||||
const blocked = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', path: dir } })
|
||||
await expect(blocked.init()).rejects.toThrow(/another writer holds/i)
|
||||
// Don't track `blocked` for afterEach cleanup since init failed.
|
||||
})
|
||||
|
|
@ -113,22 +113,22 @@ describe('Multi-process safety + read-only mode', () => {
|
|||
it('allows a second in-process writer with a warning (same PID)', async () => {
|
||||
// Two Brainy instances in the same Node process: not the dangerous
|
||||
// cross-process case. Should succeed (with a console warning).
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', rootDirectory: dir } })
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', path: dir } })
|
||||
await writer.init()
|
||||
|
||||
const second = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', rootDirectory: dir } })
|
||||
const second = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', path: dir } })
|
||||
await expect(second.init()).resolves.toBeUndefined()
|
||||
await second.close()
|
||||
})
|
||||
|
||||
it('lets a reader open while a writer is live', async () => {
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', rootDirectory: dir } })
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', path: dir } })
|
||||
await writer.init()
|
||||
await writer.add({ data: 'concurrent', type: NounType.Concept })
|
||||
await writer.flush()
|
||||
|
||||
reader = await Brainy.openReadOnly({
|
||||
storage: { type: 'filesystem', rootDirectory: dir }
|
||||
storage: { type: 'filesystem', path: dir }
|
||||
})
|
||||
const stats = await reader.stats()
|
||||
expect(stats.mode).toBe('reader')
|
||||
|
|
@ -137,11 +137,11 @@ describe('Multi-process safety + read-only mode', () => {
|
|||
})
|
||||
|
||||
it('honors { force: true } to override an existing lock', async () => {
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', rootDirectory: dir } })
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', path: dir } })
|
||||
await writer.init()
|
||||
|
||||
const second = new Brainy({ requireSubtype: false,
|
||||
storage: { type: 'filesystem', rootDirectory: dir },
|
||||
storage: { type: 'filesystem', path: dir },
|
||||
force: true
|
||||
})
|
||||
await expect(second.init()).resolves.toBeUndefined()
|
||||
|
|
@ -151,21 +151,21 @@ describe('Multi-process safety + read-only mode', () => {
|
|||
|
||||
describe('Flush-request RPC', () => {
|
||||
it('in-process call just flushes', async () => {
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', rootDirectory: dir } })
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', path: dir } })
|
||||
await writer.init()
|
||||
const ok = await writer.requestFlush({ timeoutMs: 1000 })
|
||||
expect(ok).toBe(true)
|
||||
})
|
||||
|
||||
it('cross-instance request reaches the writer (same-process simulation)', async () => {
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', rootDirectory: dir } })
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', path: dir } })
|
||||
await writer.init()
|
||||
await writer.add({ data: 'pre-request', type: NounType.Concept })
|
||||
|
||||
// openReadOnly() in the same Node process — the storage will still hit
|
||||
// the writer's flush watcher via the shared filesystem.
|
||||
reader = await Brainy.openReadOnly({
|
||||
storage: { type: 'filesystem', rootDirectory: dir }
|
||||
storage: { type: 'filesystem', path: dir }
|
||||
})
|
||||
const acked = await reader.requestFlush({ timeoutMs: 3000 })
|
||||
expect(acked).toBe(true)
|
||||
|
|
@ -174,7 +174,7 @@ describe('Multi-process safety + read-only mode', () => {
|
|||
it('returns false when no writer is running', async () => {
|
||||
// Seed some data, then close the writer. The data dir exists but no
|
||||
// writer is listening for flush requests.
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', rootDirectory: dir } })
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', path: dir } })
|
||||
await writer.init()
|
||||
await writer.add({ data: 'orphan', type: NounType.Concept })
|
||||
await writer.flush()
|
||||
|
|
@ -182,7 +182,7 @@ describe('Multi-process safety + read-only mode', () => {
|
|||
writer = null
|
||||
|
||||
reader = await Brainy.openReadOnly({
|
||||
storage: { type: 'filesystem', rootDirectory: dir }
|
||||
storage: { type: 'filesystem', path: dir }
|
||||
})
|
||||
const acked = await reader.requestFlush({ timeoutMs: 1500 })
|
||||
expect(acked).toBe(false)
|
||||
|
|
@ -191,7 +191,7 @@ describe('Multi-process safety + read-only mode', () => {
|
|||
|
||||
describe('Diagnostics on a reader', () => {
|
||||
beforeEach(async () => {
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', rootDirectory: dir } })
|
||||
writer = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', path: dir } })
|
||||
await writer.init()
|
||||
await writer.add({ data: 'one', type: NounType.Concept, metadata: { tag: 'a' } })
|
||||
await writer.add({ data: 'two', type: NounType.Concept, metadata: { tag: 'b' } })
|
||||
|
|
@ -200,7 +200,7 @@ describe('Multi-process safety + read-only mode', () => {
|
|||
|
||||
it('stats() reports counts, mode, and writer lock metadata', async () => {
|
||||
reader = await Brainy.openReadOnly({
|
||||
storage: { type: 'filesystem', rootDirectory: dir }
|
||||
storage: { type: 'filesystem', path: dir }
|
||||
})
|
||||
const stats = await reader.stats()
|
||||
expect(stats.mode).toBe('reader')
|
||||
|
|
@ -218,7 +218,7 @@ describe('Multi-process safety + read-only mode', () => {
|
|||
|
||||
it('explain() flags a field with no index entries', async () => {
|
||||
reader = await Brainy.openReadOnly({
|
||||
storage: { type: 'filesystem', rootDirectory: dir }
|
||||
storage: { type: 'filesystem', path: dir }
|
||||
})
|
||||
const plan = await reader.explain({ where: { entityTypeXYZ: 'never-registered' } })
|
||||
expect(plan.fieldPlan).toHaveLength(1)
|
||||
|
|
@ -228,7 +228,7 @@ describe('Multi-process safety + read-only mode', () => {
|
|||
|
||||
it('health() returns checks with a pass/warn/fail overall', async () => {
|
||||
reader = await Brainy.openReadOnly({
|
||||
storage: { type: 'filesystem', rootDirectory: dir }
|
||||
storage: { type: 'filesystem', path: dir }
|
||||
})
|
||||
const report = await reader.health()
|
||||
expect(report.checks.length).toBeGreaterThan(0)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue