diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ee1e723..8e91a6ad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,15 +2,6 @@ All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. -### [10.3.0](https://source.soulcraft.com/soulcraft/brainy/compare/v10.2.0...v10.3.0) (2026-08-18) - -- docs(releases): the 10.3.0 consumer entry — the trust-and-provenance release (97d75649) -- fix(locks): the fence keys ownership on pid+hostname — a same-process re-open never fences its predecessor (0991cf28) -- test(budgets): iron-honest wall-clock budgets — 3x the worst honest-iron measurement (314e0e6c) -- fix(locks): live writers are never auto-evicted; evicted writers are fenced at every commit barrier (292e7c04) -- feat(log): system commits carry their origin; the attested per-id reconcile door (9ac9e706) - - ### [10.2.0](https://source.soulcraft.com/soulcraft/brainy/compare/v10.1.0...v10.2.0) (2026-08-17) - docs(releases): the 10.2.0 consumer entry — adoption completes in one call (97538e1f) diff --git a/RELEASES.md b/RELEASES.md index 49876f5a..602b84e4 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -31,41 +31,6 @@ is sometimes cited as a 7.x removal — those methods never existed on 7.x; the --- -## v10.3.0 — 2026-08-18 (the trust-and-provenance release) - -Four consumer-driven cures. Pairs with the same native accelerator line -(>=4.1.0); adopt alongside the accelerator's 4.2.0 for its paired fixes. - -- **Writer-lock fencing.** A live writer is never auto-evicted (staleness now - requires the holding process to be dead — a >60s stall is a slow writer, not - a dead one); the lock claim is atomic (no empty-file window a racer can - misread as torn); and every flush commit and transact barrier verifies lock - ownership first, so a forced-out or lock-deleted writer fails typed - (`BRAINY_WRITER_FENCED`) instead of writing on unaware — the split-brain - class a shared dev store hit is dead at all three roots. The documented - same-process re-open ("warn and take over") stays benign: ownership is - per-process. Consumers that raised stop-timeouts as mitigation can retire - them. -- **Transaction-log provenance.** `TxLogEntry` gains an optional `origin` - field — absent means a user write (existing consumers unchanged); - engine-originated commits stamp themselves (`system:embed-landing`, - `system:adoption-backfill`, `system:reconcile`), and the same stamp rides - the commit fact's meta. Activity feeds filter on fact instead of guessing; - a reported "double tick" (the deferred vector landing indistinguishable from - a user save) is cured without collapsing genuine rapid saves. -- **The attested reconcile door.** `reconcileLogDivergence(id, {attest})` - resolves the one adoption-refusing divergence class - (`log-live-canonical-absent`) with a human's word: `'deleted'` mints the - tombstone the log always lacked; `'restore'` folds the log's only copy back - into canonical; wrong-class calls refuse typed with nothing written. Loud, - narrated, single-row. -- **Iron-honest test budgets.** The wall-clock micro-budgets are recalibrated - as order-of-magnitude guards (3x the worst measurement across three machine - classes) so honest hardware differences can never again read as failures; - real performance enforcement lives in the dedicated perf lanes. - ---- - ## v10.2.0 — 2026-08-17 (adoption completes in one call) One fix, headline-sized for large stores. Pairs with the same native accelerator diff --git a/package-lock.json b/package-lock.json index a5913ac7..e8c238f5 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@soulcraft/brainy", - "version": "10.3.0", + "version": "10.2.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@soulcraft/brainy", - "version": "10.3.0", + "version": "10.2.0", "license": "MIT", "dependencies": { "@msgpack/msgpack": "^3.1.2", diff --git a/package.json b/package.json index 241f23a8..a366f42f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@soulcraft/brainy", - "version": "10.3.0", + "version": "10.2.0", "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. Stage 3 CANONICAL: 42 nouns × 127 verbs covering 96-97% of all human knowledge.", "main": "dist/index.js", "module": "dist/index.js", diff --git a/src/brainy.ts b/src/brainy.ts index d1ec144b..addb8bc2 100644 --- a/src/brainy.ts +++ b/src/brainy.ts @@ -2245,8 +2245,7 @@ export class Brainy implements BrainyInterface { }, undefined, undefined, - [{ type: 'embed.landed', id, vector: newVector }], - 'system:embed-landing' + [{ type: 'embed.landed', id, vector: newVector }] ) this.clearPendingEmbed(id) } catch (err) { @@ -2480,8 +2479,7 @@ export class Brainy implements BrainyInterface { run: TransactionFunction, precommit?: (before: CommitBeforeImages) => void, pendingEvents?: PendingChangeEvent[], - records?: FactMarkerRecord[], - origin?: string + records?: FactMarkerRecord[] ): Promise<{ generation?: number; timestamp: number; degraded?: string[] }> { // Change-feed capture: when this write will emit, hold a reference to the // commit's before-images so `remove` events can carry the record's last @@ -2544,7 +2542,6 @@ export class Brainy implements BrainyInterface { touched, precommit: captureAndCheck, ...(records && records.length > 0 ? { records } : {}), - ...(origin ? { origin } : {}), execute: () => this.transactionManager.executeTransaction(run, { timeout: transactTimeoutBudget( @@ -8361,7 +8358,7 @@ export class Brainy implements BrainyInterface { } } }) - }, undefined, undefined, undefined, 'system:adoption-backfill') + }) } const next = await this.runOracle({ listAll: true }) // THE ONLY STOP: no progress. With uncapped listings both counts are @@ -8395,137 +8392,6 @@ export class Brainy implements BrainyInterface { return report } - /** - * @description THE ATTESTED PER-ID RECONCILE DOOR for the one divergence - * class the adoption backfill refuses BY DESIGN: `log-live-canonical-absent` - * — the log holds a live record for a row the canonical tree says does not - * exist. The engine cannot tell a legitimate pre-log deletion (the log - * missed the tombstone — the deferred-durability-era ack-window class) from - * canonical LOSS (the log holds the only surviving copy); auto-curing would - * silently destroy data in one of the two readings. A HUMAN attests which: - * - * - `attest: 'deleted'` — the row was legitimately deleted; mint the - * tombstone fact the log always lacked (canonical stays absent). The - * log's history keeps the old live record — as-of reads before the - * tombstone still see it. - * - `attest: 'restore'` — canonical lost the row; fold the log's latest - * after-image back into canonical (both sides now agree it lives). - * - * Loud, narrated, single-row, and stamped `origin: 'system:reconcile'` on - * both the tx-log entry and the commit fact. Refuses (typed) when the id's - * log and canonical already agree, when `restore` is attested but the log - * holds no record, and when canonical is PRESENT-but-different (that is - * `state-differs` — `adoptLogAuthority()`'s backfill owns it). - * - * @param id - The single entity id to reconcile. - * @param options.attest - The human's word on which reading is true. - * @returns What was done and the generation that recorded it. - * @throws When the divergence is not the attested class (nothing is written). - */ - async reconcileLogDivergence( - id: string, - options: { attest: 'deleted' | 'restore' } - ): Promise<{ reconciled: 'tombstoned' | 'restored'; id: string; generation: number }> { - await this.ensureInitialized() - this.assertWritable('reconcileLogDivergence') - - // Fold the log for THIS id (one scan; a rare operator door). - const scan = this.scanFacts() - if (!scan) { - throw new Error('reconcileLogDivergence: this store has no fact log — nothing to reconcile against') - } - let logLatest: { tombstoned: boolean; record: { metadata: unknown; vector: unknown } | null } | null = null - for await (const batch of scan.batches()) { - for (const fact of batch.facts) { - for (const op of fact.ops) { - if (op.kind === 'noun' && op.id === id) { - logLatest = - op.record === null - ? { tombstoned: true, record: null } - : { tombstoned: false, record: { metadata: op.record.metadata, vector: op.record.vector } } - } - } - } - } - const canonical = await this.storage.readNounRaw(id) - const canonicalAbsent = canonical.metadata === null && canonical.vector === null - - // Only the log-live + canonical-absent shape passes; everything else - // names its actual state and the door that owns it. - if (!logLatest || logLatest.tombstoned) { - throw new Error( - `reconcileLogDivergence(${id}): the log's latest state is ` + - `${logLatest ? 'a tombstone' : 'no record at all'} — there is no ` + - `log-live-canonical-absent divergence here. If the oracle reports this id, ` + - `re-run verifyLogAuthority() for the current class.` - ) - } - if (!canonicalAbsent) { - throw new Error( - `reconcileLogDivergence(${id}): canonical is PRESENT — this is not the ` + - `log-live-canonical-absent class. If canonical differs from the log ` + - `(state-differs), adoptLogAuthority()'s backfill cures it; nothing was written.` - ) - } - - if (options.attest === 'deleted') { - // Mint the tombstone fact the log always lacked. writeNounRaw with null - // parts is an idempotent delete; the commit fact reads canonical back - // after execute (absent) and records the tombstone. - const receipt = await this.persistSingleOp( - { nouns: [id] }, - async (tx) => { - tx.addOperation({ - name: 'ReconcileTombstone', - execute: async () => { - await this.storage.writeNounRaw(id, { metadata: null, vector: null }) - return async () => { - // Undo of an idempotent delete of an absent row: nothing. - } - } - }) - }, - undefined, - undefined, - undefined, - 'system:reconcile' - ) - prodLog.warn( - `[Brainy] reconcileLogDivergence: ${id} attested DELETED — tombstone fact minted ` + - `at generation ${receipt.generation}; the log now agrees the row is gone ` + - `(its history keeps the earlier live record).` - ) - return { reconciled: 'tombstoned', id, generation: receipt.generation! } - } - - // attest: 'restore' — the log's copy is the survivor; fold it back. - const record = logLatest.record! - const receipt = await this.persistSingleOp( - { nouns: [id] }, - async (tx) => { - tx.addOperation({ - name: 'ReconcileRestore', - execute: async () => { - await this.storage.writeNounRaw(id, record) - return async () => { - await this.storage.writeNounRaw(id, { metadata: null, vector: null }) - } - } - }) - }, - undefined, - undefined, - undefined, - 'system:reconcile' - ) - prodLog.warn( - `[Brainy] reconcileLogDivergence: ${id} attested RESTORE — the log's latest ` + - `after-image was folded back into canonical at generation ${receipt.generation}. ` + - `Derived indexes reconcile at next open/repairIndex; the row serves from canonical now.` - ) - return { reconciled: 'restored', id, generation: receipt.generation! } - } - /** * @description Read the reified transaction log — one entry per committed * generation, carrying the committed generation, the commit timestamp, and diff --git a/src/db/generationStore.ts b/src/db/generationStore.ts index 065b3659..4002c1ba 100644 --- a/src/db/generationStore.ts +++ b/src/db/generationStore.ts @@ -428,13 +428,7 @@ export class GenerationStore { private pendingGens: number[] = [] private readonly pendingBuffer = new Map< number, - { - nouns: Map - verbs: Map - timestamp: number - /** Engine-origin stamp for the tx-log entry (absent = user write). */ - origin?: string - } + { nouns: Map; verbs: Map; timestamp: number } >() /** Pending timer-coalesced flush handle (cleared on flush/close). */ private pendingFlushTimer: ReturnType | null = null @@ -1394,10 +1388,6 @@ export class GenerationStore { // The transaction's entire canonical footprint is now durable, so the // counter/manifest advance below can never outrun the entity bytes. await this.storage.flushWriteBarrier?.() - // THE FENCE (transact leg): verify lock ownership before the commit - // point — an aborted-by-fence transact rolls back cleanly through the - // catch below; a fenced writer must never advance counter or manifest. - await this.storage.assertWriterFenceHeld?.() faultPoint('after-execute') // Fact log (dual-write): append + fsync this generation's AFTER-IMAGE @@ -1652,12 +1642,6 @@ export class GenerationStore { * surfacing that honestly. */ records?: FactMarkerRecord[] - /** - * Engine-origin stamp (`'system:embed-landing'`, `'system:adoption-backfill'`, - * `'system:reconcile'`). Rides the tx-log entry AND the commit fact's meta, - * so both records agree about WHO committed. Absent = user write. - */ - origin?: string }): Promise<{ generation: number; timestamp: number; degraded?: string[] }> { return this.withMutex(async () => { // Refuse to accept a write whose history we cannot make durable: if the @@ -1726,7 +1710,7 @@ export class GenerationStore { // incomplete for these ids until the next rebuild/repairIndex (the // egress guard prevents wrong results meanwhile). Loud, honest, // no double-write. - this.pendingBuffer.set(gen, { nouns: nounBefore, verbs: verbBefore, timestamp, ...(args.origin ? { origin: args.origin } : {}) }) + this.pendingBuffer.set(gen, { nouns: nounBefore, verbs: verbBefore, timestamp }) this.pendingGens.push(gen) this.extendChains(gen, nouns, verbs) // The adopted generation is committed — it gets its fact like any @@ -1739,7 +1723,6 @@ export class GenerationStore { timestamp, nouns, verbs, - ...(args.origin ? { meta: { origin: args.origin } } : {}), ...(args.records && args.records.length > 0 ? { records: args.records } : {}) }) ) @@ -1780,7 +1763,7 @@ export class GenerationStore { if (this.commitFaultInjector) this.commitFaultInjector('singleop-after-execute') // Buffer the pending generation + make it instantly visible to reads. - this.pendingBuffer.set(gen, { nouns: nounBefore, verbs: verbBefore, timestamp, ...(args.origin ? { origin: args.origin } : {}) }) + this.pendingBuffer.set(gen, { nouns: nounBefore, verbs: verbBefore, timestamp }) this.pendingGens.push(gen) this.extendChains(gen, nouns, verbs) // Fact log (dual-write): the acked write's AFTER-IMAGE fact, appended @@ -1819,7 +1802,6 @@ export class GenerationStore { timestamp, nouns, verbs, - ...(args.origin ? { meta: { origin: args.origin } } : {}), ...(args.records && args.records.length > 0 ? { records: args.records } : {}) }) ) @@ -1919,11 +1901,6 @@ export class GenerationStore { private async flushPendingSingleOpsUnlocked(): Promise { return this.withMutex(async () => { if (this.pendingGens.length === 0) return - // THE FENCE: an evicted writer (force-takeover, removed lock) must fail - // HERE, before a single staged byte or manifest advance — writing on - // after eviction is how split-brain stores are made. One small read - // per flush window. - await this.storage.assertWriterFenceHeld?.() this.clearPendingFlushTimer() const gens = [...this.pendingGens].sort((a, b) => a - b) @@ -1981,7 +1958,7 @@ export class GenerationStore { const deltaPath = `${dir}/tx.json` await this.storage.writeRawObject(deltaPath, delta) stagedPaths.push(deltaPath) - logEntries.push({ generation: gen, timestamp: buf.timestamp, ...(buf.origin ? { origin: buf.origin } : {}) }) + logEntries.push({ generation: gen, timestamp: buf.timestamp }) } // Test-only crash simulation. A crash here must cost only the window's diff --git a/src/db/types.ts b/src/db/types.ts index 363de086..2c7eab8f 100644 --- a/src/db/types.ts +++ b/src/db/types.ts @@ -412,17 +412,6 @@ export interface TxLogEntry { timestamp: number /** Transaction metadata, when supplied to `transact()`. */ meta?: Record - /** - * WHO committed. Absent = a user write (every pre-existing consumer's - * reading stays exact). Engine-originated commits stamp themselves — - * `'system:embed-landing'` (the deferred vector landing), - * `'system:adoption-backfill'` (baseline re-commits), `'system:reconcile'` - * (the attested per-id divergence door) — so activity feeds can filter on - * fact instead of collapsing near-in-time entries (a consumer refused that - * heuristic as a quiet loss, correctly; this field is the honest cure). - * The same stamp rides the commit fact's meta, so log and tx-log agree. - */ - origin?: string } // ============================================================================ @@ -485,16 +474,6 @@ export interface GenerationStorage { */ syncEntityCanonical?(nouns: string[], verbs: string[]): Promise - /** - * OPTIONAL writer fence: throw `BRAINY_WRITER_FENCED` when this instance - * no longer owns the store's writer lock (an operator force-takeover or a - * removed lock file). Called at every flush commit and transact barrier — - * one small read per commit window — so an evicted writer fails loudly on - * its next commit instead of split-braining the store. Adapters without a - * cross-process lock model omit it. - */ - assertWriterFenceHeld?(): Promise - /** Read an entity's raw stored metadata+vector objects. */ readNounRaw(id: string): Promise<{ metadata: any | null; vector: any | null }> /** Restore an entity's raw stored objects (`null` part ⇒ delete that file). */ diff --git a/src/storage/adapters/fileSystemStorage.ts b/src/storage/adapters/fileSystemStorage.ts index b8e2a9af..81c6e545 100644 --- a/src/storage/adapters/fileSystemStorage.ts +++ b/src/storage/adapters/fileSystemStorage.ts @@ -1920,24 +1920,14 @@ export class FileSystemStorage extends BaseStorage { rootDir: this.rootDir } - // The atomic claim: write the FULL contents to a temp file, then - // hard-link it into place — link(2) fails EEXIST if the target exists, - // and the lock file appears with its complete JSON in one atomic step. - // (The previous claim was writeFile with O_EXCL, whose open→write→close - // is NOT atomic: a concurrent opener could read the file in its empty - // window, judge it torn, unlink a LIVE claim, and take the lock — two - // live writers. The link claim leaves no empty window to misread.) - const claimTmp = `${lockFile}.claim-${myPid}-${Date.now()}` + // The atomic claim: create-exclusive, so exactly ONE racer wins. try { - await fs.promises.writeFile(claimTmp, JSON.stringify(info, null, 2)) - await fs.promises.link(claimTmp, lockFile) + await fs.promises.writeFile(lockFile, JSON.stringify(info, null, 2), { flag: 'wx' }) } catch (err: any) { if (err.code === 'EEXIST') { continue // someone else claimed between our read and create — re-evaluate } throw err - } finally { - await fs.promises.unlink(claimTmp).catch(() => {}) } this.installWriterLock(info) @@ -1982,51 +1972,6 @@ export class FileSystemStorage extends BaseStorage { } } - /** - * THE FENCE: verify this instance still owns the writer lock before a - * commit barrier proceeds. An evicted writer (an operator's - * `{ force: true }` takeover, or an operator deleting the lock file) must - * fail LOUDLY on its next flush instead of writing on unaware — the - * unfenced evicted writer was half of a production split-brain (each - * writer flushing its own internally-consistent id-mapper snapshot, - * alternating the store between two truths). One small file read per - * flush window, never per record. No-op when this instance holds no - * writer lock (read-only opens, in-memory stores). - * - * @throws `BRAINY_WRITER_FENCED` when the lock is gone or held by another. - */ - public override async assertWriterFenceHeld(): Promise { - if (!this.writerLockInfo) return - const current = await this.readWriterLock() - // Ownership is PER-PROCESS: pid + hostname, deliberately NOT startedAt. - // The documented same-process re-open path ("warn and take over" — two - // instances in one Node process, the server-restart test pattern) - // rewrites the lock with a fresh startedAt; fencing the first instance - // on that mismatch latched its background flushes dead while its own - // process held the lock (caught by the plant's integration lane, twice). - // startedAt adds nothing against pid recycling either: a recycled pid's - // victim is a DEAD process — it runs no fence checks. - if ( - current && - current.pid === this.writerLockInfo.pid && - current.hostname === this.writerLockInfo.hostname - ) { - return - } - const err = new Error( - `Writer fence lost for ${this.rootDir}: this process (PID ${this.writerLockInfo.pid}) ` + - `no longer holds the writer lock — ` + - (current - ? `it is now held by PID ${current.pid} on ${current.hostname} (since ${current.startedAt}).` - : `the lock file is gone (released or removed by an operator).`) + - `\nThis instance refuses to commit further writes: a fenced-out writer continuing to ` + - `flush is how split-brain stores are made. Close this instance; if the takeover was a ` + - `mistake, close the successor and re-open.` - ) as Error & { code: string } - err.code = 'BRAINY_WRITER_FENCED' - throw err - } - /** The consumer-facing BRAINY_WRITER_LOCKED error, holder details attached. */ private writerLockedError(existing: WriterLockInfo): Error { const err = new Error( @@ -2115,25 +2060,18 @@ export class FileSystemStorage extends BaseStorage { /** * Determine whether an existing writer lock is stale (safe to overwrite). - * Same hostname and DEAD PID → stale. That is the whole rule: a LIVE - * process is never auto-evicted, however old its heartbeat — a >60s - * event-loop stall (debugger pause, GC, heavy sync work) is a slow writer, - * not a dead one, and heartbeat-age eviction of live writers was the - * dominant mechanism behind a production split-brain (two live unaware - * writers alternating a store's id-mapper between two truths). A holder - * that LOOKS alive but is truly wedged is the operator's call via - * `{ force: true }` — and the fence check on every flush - * ({@link assertWriterFenceHeld}) guarantees a forced-out holder fails - * loudly instead of writing on. Different hostname → cannot prove - * anything, treat as live. The heartbeat remains for OBSERVABILITY (the - * lock error names it so an operator can judge staleness themselves). + * Same hostname and (dead PID OR heartbeat older than threshold) → stale. + * Different hostname → cannot prove stale, treat as live. */ private async isWriterLockStale(lock: WriterLockInfo): Promise { const os = await import('node:os') if (lock.hostname !== os.hostname()) { return false } - return !this.isPidAlive(lock.pid) + const heartbeatAge = Date.now() - new Date(lock.lastHeartbeat).getTime() + const pidAlive = this.isPidAlive(lock.pid) + if (!pidAlive) return true + return heartbeatAge > FileSystemStorage.WRITER_STALE_THRESHOLD_MS } /** diff --git a/src/storage/baseStorage.ts b/src/storage/baseStorage.ts index b65e938e..c3b3b3bf 100644 --- a/src/storage/baseStorage.ts +++ b/src/storage/baseStorage.ts @@ -612,18 +612,6 @@ export abstract class BaseStorage extends BaseStorageAdapter { return null } - /** - * THE FENCE: verify this instance still owns its writer lock before a - * commit barrier proceeds; throw `BRAINY_WRITER_FENCED` if evicted. The - * default is a no-op — adapters without a cross-process lock model (memory, - * per-request cloud stores) have no eviction to fence against. The - * filesystem adapter overrides this; the generation store calls it at - * every flush commit and transact barrier. - */ - public async assertWriterFenceHeld(): Promise { - // No-op by default — no lock model, nothing to be evicted from. - } - /** * Start watching for cross-process flush requests. The writer Brainy * instance calls this so that out-of-process inspectors can ask for a diff --git a/tests/integration/find-unified-integration.test.ts b/tests/integration/find-unified-integration.test.ts index 94053d55..4370295e 100644 --- a/tests/integration/find-unified-integration.test.ts +++ b/tests/integration/find-unified-integration.test.ts @@ -709,14 +709,8 @@ describe('Unified Find() Integration Tests', () => { expect(simpleResult.length).toBeGreaterThan(0) expect(complexResult.length).toBeGreaterThan(0) - // These are both sub-millisecond operations on tiny fixture data, so - // comparing two microsecond-scale timings for absolute equality-class - // ordering (simple <= complex) can never be stable — timer - // resolution and scheduling noise dominate the signal. Assert only - // the order-of-magnitude property: the simple path isn't - // dramatically slower than the complex one. The +5ms floor absorbs - // noise when complexDuration itself rounds to ~0. - expect(simpleDuration).toBeLessThanOrEqual(complexDuration * 3 + 5) + // Simple queries should be faster + expect(simpleDuration).toBeLessThanOrEqual(complexDuration) }) it('should use fast paths for single search types', async () => { diff --git a/tests/integration/remaining-apis.test.ts b/tests/integration/remaining-apis.test.ts index f7cd17e9..12d60983 100644 --- a/tests/integration/remaining-apis.test.ts +++ b/tests/integration/remaining-apis.test.ts @@ -367,9 +367,7 @@ Gadget,20` const time = Date.now() - start expect(entries.length).toBe(20) - // order-of-magnitude guard: worst honest-iron measurement 8.85s - // (32-core CPU-only box), 3x headroom - expect(time).toBeLessThan(30000) + expect(time).toBeLessThan(5000) // < 5 seconds console.log(` ✅ Created and copied 20 files in ${time}ms`) }) }) diff --git a/tests/integration/txlog-origin-and-reconcile.test.ts b/tests/integration/txlog-origin-and-reconcile.test.ts deleted file mode 100644 index fbe05fcf..00000000 --- a/tests/integration/txlog-origin-and-reconcile.test.ts +++ /dev/null @@ -1,142 +0,0 @@ -/** - * @module tests/integration/txlog-origin-and-reconcile - * @description Two consumer-driven cures, pinned together because they share - * the origin stamp: - * - * 1. TX-LOG ORIGIN — engine-originated commits stamp `origin` on their - * tx-log entry (and the commit fact's meta) so activity feeds filter on - * fact: a downstream feed showed a "double tick" because the deferred - * vector-landing commit was indistinguishable from a user save, and the - * consumer rightly refused a time-window collapse as a quiet loss. User - * writes stay UNSTAMPED (absent origin) — the pre-existing reading of - * every consumer is exact. - * - * 2. THE RECONCILE DOOR — `log-live-canonical-absent` refuses auto-cure by - * design (a legitimate lost-tombstone deletion is indistinguishable from - * canonical loss); `reconcileLogDivergence(id, {attest})` is the human's - * door: 'deleted' mints the missing tombstone, 'restore' folds the log's - * copy back, wrong-class calls refuse typed with nothing written. - */ -import { describe, it, expect, afterEach } from 'vitest' -import { mkdtempSync, rmSync } from 'node:fs' -import { tmpdir } from 'node:os' -import { join } from 'node:path' -import { Brainy } from '../../src/index.js' -import { NounType } from '../../src/types/graphTypes.js' - -type RawBox = { - storage: { - readNounRaw(id: string): Promise<{ metadata: unknown; vector: unknown }> - writeNounRaw(id: string, r: { metadata: unknown; vector: unknown }): Promise - } -} - -const dirs: string[] = [] -const brains: Brainy[] = [] -afterEach(async () => { - for (const b of brains.splice(0)) await b.close().catch(() => {}) - for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true }) -}) - -async function fsBrain(): Promise { - const dir = mkdtempSync(join(tmpdir(), 'brainy-origin-reconcile-')) - dirs.push(dir) - const brain = new Brainy({ - storage: { type: 'filesystem', path: dir }, - requireSubtype: false - }) - await brain.init() - brains.push(brain) - return brain -} - -describe('tx-log origin stamp', () => { - it('the deferred-embed landing commit is stamped system:embed-landing; the user write is not', async () => { - const brain = await fsBrain() - await brain.add({ - data: 'a row whose vector lands later', - type: NounType.Document, - metadata: { k: 1 }, - deferEmbedding: true - }) - await brain.awaitPendingEmbeds() - await brain.flush() - - const entries = await brain.transactionLog() - const system = entries.filter((e) => (e as { origin?: string }).origin === 'system:embed-landing') - const user = entries.filter((e) => !(e as { origin?: string }).origin) - expect(system.length, 'the landing commit is stamped').toBeGreaterThanOrEqual(1) - expect(user.length, 'the user add stays unstamped').toBeGreaterThanOrEqual(1) - // The feed cure in one line: filtering !origin removes the double tick. - expect(user.length).toBeLessThan(entries.length) - }, 120000) -}) - -describe('reconcileLogDivergence — the attested door', () => { - /** Manufacture the class: a live log record whose canonical row is gone. */ - async function manufactureDivergence(brain: Brainy): Promise { - const id = await brain.add({ - data: 'pre-era row whose deletion the log never saw', - type: NounType.Document, - metadata: { era: 'pre-spine' } - }) - await brain.flush() - // Delete canonical BEHIND the log's back (raw write, no generation) — - // exactly the shape a deferred-durability-era crash left behind. - const storage = (brain as unknown as RawBox).storage - await storage.writeNounRaw(id, { metadata: null, vector: null }) - return id - } - - it("attest:'deleted' mints the missing tombstone — the oracle goes green and the commit is stamped system:reconcile", async () => { - const brain = await fsBrain() - const id = await manufactureDivergence(brain) - const before = await brain.verifyLogAuthority() - expect( - before.mismatches.some((m) => m.id === id && m.reason === 'log-live-canonical-absent'), - 'the manufactured divergence is oracle-visible as the refused class' - ).toBe(true) - - const result = await brain.reconcileLogDivergence(id, { attest: 'deleted' }) - expect(result.reconciled).toBe('tombstoned') - - const after = await brain.verifyLogAuthority() - expect(after.mismatches.some((m) => m.id === id), 'the id no longer diverges').toBe(false) - expect(await brain.get(id), 'canonical stays absent').toBeNull() - - await brain.flush() - const entries = await brain.transactionLog() - expect( - entries.some((e) => (e as { origin?: string }).origin === 'system:reconcile'), - 'the reconcile commit is origin-stamped' - ).toBe(true) - }, 120000) - - it("attest:'restore' folds the log's copy back into canonical", async () => { - const brain = await fsBrain() - const id = await manufactureDivergence(brain) - - const result = await brain.reconcileLogDivergence(id, { attest: 'restore' }) - expect(result.reconciled).toBe('restored') - - const row = await brain.get(id) - expect(row, 'the log’s only copy lives again').not.toBeNull() - expect((row!.metadata as { era: string }).era).toBe('pre-spine') - expect((await brain.verifyLogAuthority()).mismatches.some((m) => m.id === id)).toBe(false) - }, 120000) - - it('wrong-class calls refuse typed with nothing written', async () => { - const brain = await fsBrain() - const id = await brain.add({ data: 'healthy row', type: NounType.Document, metadata: { n: 1 } }) - await brain.flush() - // Canonical present + log agrees: not the class — refuse, name the state. - await expect(brain.reconcileLogDivergence(id, { attest: 'deleted' })).rejects.toThrow( - /canonical is PRESENT/ - ) - expect(await brain.get(id), 'nothing was written').not.toBeNull() - // Unknown id: no log record at all — refuse, name it. - await expect( - brain.reconcileLogDivergence('00000000-0000-7000-8000-00000000dead', { attest: 'restore' }) - ).rejects.toThrow(/no record at all/) - }, 120000) -}) diff --git a/tests/integration/writer-lock-fencing.test.ts b/tests/integration/writer-lock-fencing.test.ts deleted file mode 100644 index e9f98dac..00000000 --- a/tests/integration/writer-lock-fencing.test.ts +++ /dev/null @@ -1,148 +0,0 @@ -/** - * @module tests/integration/writer-lock-fencing - * @description The writer-lock fencing cures, from a production dev-store - * split-brain (two live writers alternating a store's id-mapper between two - * internally-consistent truths). Three laws, each pinned: - * - * 1. A LIVE writer is never auto-evicted — staleness requires PID-death. - * (The old rule evicted on heartbeat age alone, so a >60s event-loop - * stall — debugger, GC — handed the lock to a second opener while the - * first kept writing.) - * 2. A DEAD writer's lock still self-clears with narration (venue's ask). - * 3. THE FENCE: an evicted writer (force-takeover or removed lock) fails - * LOUDLY at its next commit barrier — typed BRAINY_WRITER_FENCED — and - * never advances the store. - */ -import { describe, it, expect, afterEach } from 'vitest' -import * as fs from 'node:fs' -import * as os from 'node:os' -import { mkdtempSync, rmSync } from 'node:fs' -import { tmpdir } from 'node:os' -import { join } from 'node:path' -import { Brainy } from '../../src/index.js' -import { NounType } from '../../src/types/graphTypes.js' - -const dirs: string[] = [] -const brains: Brainy[] = [] -afterEach(async () => { - for (const b of brains.splice(0)) await b.close().catch(() => {}) - for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true }) -}) - -function lockPath(dir: string): string { - return join(dir, 'locks', '_writer.lock') -} - -async function fsBrain(dir: string): Promise { - const brain = new Brainy({ - storage: { type: 'filesystem', path: dir }, - requireSubtype: false - }) - await brain.init() - brains.push(brain) - return brain -} - -describe('writer-lock fencing', () => { - it('a LIVE writer with an ancient heartbeat is NOT evicted — the second opener refuses typed', async () => { - const dir = mkdtempSync(join(tmpdir(), 'brainy-fence-live-')) - dirs.push(dir) - await fsBrain(dir) - - // Manufacture the trigger shape: a DIFFERENT process's lock (pid 1 — - // always alive, never ours, EPERM proves liveness) with a >60s-old - // heartbeat — the blocked-event-loop costume that used to get evicted. - const lp = lockPath(dir) - const lock = JSON.parse(fs.readFileSync(lp, 'utf-8')) - lock.pid = 1 - lock.lastHeartbeat = new Date(Date.now() - 10 * 60_000).toISOString() - fs.writeFileSync(lp, JSON.stringify(lock)) - - // Old rule: heartbeat-age eviction → silent takeover → split brain. - // New rule: live PID = live writer; the second opener throws typed. - const second = new Brainy({ storage: { type: 'filesystem', path: dir }, requireSubtype: false }) - await expect(second.init()).rejects.toMatchObject({ code: 'BRAINY_WRITER_LOCKED' }) - }, 120000) - - it("a DEAD writer's lock self-clears and the new opener proceeds", async () => { - const dir = mkdtempSync(join(tmpdir(), 'brainy-fence-dead-')) - dirs.push(dir) - const first = await fsBrain(dir) - await first.close() - brains.pop() - - // Manufacture a crashed holder: a lock naming a PID that cannot exist. - fs.mkdirSync(join(dir, 'locks'), { recursive: true }) - fs.writeFileSync( - lockPath(dir), - JSON.stringify({ - pid: 2 ** 22 + 12345, // beyond pid_max on any default Linux - hostname: os.hostname(), - startedAt: new Date().toISOString(), - lastHeartbeat: new Date().toISOString(), - version: 'test', - rootDir: dir - }) - ) - const brain = await fsBrain(dir) // must not throw - const id = await brain.add({ data: 'post-takeover write', type: NounType.Document, metadata: {} }) - expect(await brain.get(id)).not.toBeNull() - }, 120000) - - it('the fence does NOT fire on a same-process re-open — the documented warn-and-take-over contract stays benign', async () => { - const dir = mkdtempSync(join(tmpdir(), 'brainy-fence-samepid-')) - dirs.push(dir) - const first = await fsBrain(dir) - await first.add({ data: 'first instance write', type: NounType.Document, metadata: { n: 1 } }) - - // A second instance in the SAME process takes the lock over (fresh - // startedAt) — the pattern server-restart tests use. The first - // instance's background flushes must keep working: same pid + same - // hostname IS ownership. (The plant's integration lane caught the - // startedAt-strict fence latching exactly this shape dead.) - const second = await fsBrain(dir) - await second.add({ data: 'second instance write', type: NounType.Document, metadata: { n: 2 } }) - await expect(first.flush()).resolves.toBeUndefined() - await expect(second.flush()).resolves.toBeUndefined() - }, 120000) - - it('THE FENCE: a forced-out writer fails its next flush typed and advances nothing', async () => { - const dir = mkdtempSync(join(tmpdir(), 'brainy-fence-evict-')) - dirs.push(dir) - const victim = await fsBrain(dir) - await victim.add({ data: 'pre-eviction write', type: NounType.Document, metadata: { n: 1 } }) - await victim.flush() - const genBefore = victim.generation() - - // A successor takes the lock behind the victim's back (the force-takeover - // shape: different pid + startedAt). - fs.writeFileSync( - lockPath(dir), - JSON.stringify({ - pid: process.pid + 1, - hostname: os.hostname(), - startedAt: new Date(Date.now() + 1).toISOString(), - lastHeartbeat: new Date().toISOString(), - version: 'test-successor', - rootDir: dir - }) - ) - - // The victim's next commit barrier must refuse, typed — never write on. - await victim.add({ data: 'post-eviction write', type: NounType.Document, metadata: { n: 2 } }) - await expect(victim.flush()).rejects.toMatchObject({ code: 'BRAINY_WRITER_FENCED' }) - expect(victim.generation(), 'committed watermark never advanced past the fence') - .toBeGreaterThanOrEqual(genBefore) - - // Transact leg: the barrier fences there too, and rolls back cleanly. - await expect( - victim.transact([ - { op: 'add', id: '00000000-0000-7000-8000-0000000fence', type: NounType.Document, data: 'fenced', metadata: {} } - ]) - ).rejects.toMatchObject({ code: 'BRAINY_WRITER_FENCED' }) - - // Silence the fenced instance's close-time release (it no longer owns the lock). - brains.pop() - await victim.close().catch(() => {}) - }, 120000) -}) diff --git a/tests/unit/brainy/add.test.ts b/tests/unit/brainy/add.test.ts index 10690e2f..c017862c 100644 --- a/tests/unit/brainy/add.test.ts +++ b/tests/unit/brainy/add.test.ts @@ -452,11 +452,9 @@ describe('Brainy.add()', () => { }) // Act & Assert - // order-of-magnitude guard: worst honest-iron measurement 105ms - // (5% over the old 100ms budget), 3x headroom on the overage class await assertCompletesWithin( () => brain.add(params), - 300, + 100, // Should complete within 100ms 'Add operation' ) }) diff --git a/tests/unit/brainy/batch-operations.test.ts b/tests/unit/brainy/batch-operations.test.ts index 889127ee..58b25744 100644 --- a/tests/unit/brainy/batch-operations.test.ts +++ b/tests/unit/brainy/batch-operations.test.ts @@ -456,9 +456,7 @@ describe('Brainy Batch Operations', () => { // Verify batch operation completed successfully // Note: Performance can vary based on system load and embedding generation expect(batchIds).toHaveLength(itemCount) - // order-of-magnitude guard: worst honest-iron measurement 11.9s (CPU-only - // inference, 32-core box), 3x headroom for 50-item batch - expect(batchTime).toBeLessThan(40000) + expect(batchTime).toBeLessThan(5000) // Reasonable timeout for 50 items console.log(`Individual: ${individualTime}ms, Batch: ${batchTime}ms`) if (batchTime < individualTime) { @@ -512,9 +510,7 @@ describe('Brainy Batch Operations', () => { const totalTime = Date.now() - startTime - // order-of-magnitude guard: worst honest-iron measurement 6652ms - // (mixed batch under CPU-only inference), 3x headroom - expect(totalTime).toBeLessThan(20000) + expect(totalTime).toBeLessThan(3000) // v5.4.0: Type-first storage takes longer // Verify final state const remaining = await brain.get(initialIds[0]) @@ -560,12 +556,7 @@ describe('Brainy Batch Operations', () => { // Might throw if there's a limit expect(error).toBeDefined() } - // order-of-magnitude guard: this test batches 20x the item count of the - // sibling "perform better" test above (worst measured 11.9s for 50 - // items on CPU-only honest iron); the prior 60s timeout was itself - // observed being hit, so this is 3x that floor rather than a scaled - // extrapolation, to leave real headroom for run-to-run variance - }, 180000) + }, 60000) it('should provide meaningful error messages', async () => { try { diff --git a/tests/unit/brainy/find.test.ts b/tests/unit/brainy/find.test.ts index 5bead272..c9b36e64 100644 --- a/tests/unit/brainy/find.test.ts +++ b/tests/unit/brainy/find.test.ts @@ -375,13 +375,11 @@ describe('Brainy.find()', () => { limit: 10 }) const duration = Date.now() - start - + // Assert - // order-of-magnitude guard: worst honest-iron measurement 106ms - // (6% over the old 100ms budget), 3x headroom on the overage class - expect(duration).toBeLessThan(300) + expect(duration).toBeLessThan(100) }) - + it('should handle large result sets efficiently', async () => { // Arrange - Add many entities await Promise.all( diff --git a/tests/unit/neural/NaturalLanguageProcessor.test.ts b/tests/unit/neural/NaturalLanguageProcessor.test.ts index 79cf9b6e..0800601e 100644 --- a/tests/unit/neural/NaturalLanguageProcessor.test.ts +++ b/tests/unit/neural/NaturalLanguageProcessor.test.ts @@ -343,11 +343,9 @@ describe('NaturalLanguageProcessor', () => { const duration = Date.now() - startTime expect(result).toBeDefined() - // order-of-magnitude guard: worst honest-iron measurement 4.8s - // (CPU-only inference path, 32-core box); 15s budget covers 3x that - expect(duration).toBeLessThan(15000) + expect(duration).toBeLessThan(200) // Should be fast }) - + it('should handle multiple queries efficiently', async () => { const queries = Array(10).fill('Find AI research') @@ -358,10 +356,8 @@ describe('NaturalLanguageProcessor', () => { const duration = Date.now() - startTime expect(results).toHaveLength(10) - // order-of-magnitude guard: worst honest-iron measurement 48.2s for 10 - // concurrent inference-path queries (CPU-only, 32-core box); ~3x headroom - expect(duration).toBeLessThan(150000) - }, 200000) + expect(duration).toBeLessThan(2000) // Should handle batch in reasonable time + }) it('should cache pattern matching for performance', async () => { const query = 'Find machine learning papers' diff --git a/tests/unit/neural/signals/EmbeddingSignal.test.ts b/tests/unit/neural/signals/EmbeddingSignal.test.ts index 54d34b64..f1ff5beb 100644 --- a/tests/unit/neural/signals/EmbeddingSignal.test.ts +++ b/tests/unit/neural/signals/EmbeddingSignal.test.ts @@ -218,10 +218,7 @@ describe('EmbeddingSignal', () => { const finalStats = signal.getStats() expect(finalStats.historySize).toBeLessThanOrEqual(1000) // MAX_HISTORY = 1000 - // Inference-bound correctness test (hundreds of real embeds): measured - // 116-174s on honest CPU-only iron across three machines — the timeout - // covers the slowest observed with headroom; the assertions are exact. - }, 600000) + }) it('should clear history', async () => { const vector = await brain.embed('Test') @@ -580,9 +577,8 @@ describe('EmbeddingSignal', () => { const endTime = Date.now() const totalTime = endTime - startTime - // order-of-magnitude guard: worst honest-iron measurement 22.3s - // (CPU-only inference, 32-core box) for 100 entities, 3x headroom - expect(totalTime).toBeLessThan(70000) + // Should be reasonably fast (< 5 seconds for 100 entities) + expect(totalTime).toBeLessThan(5000) const stats = signal.getStats() expect(stats.calls).toBe(100)