diff --git a/src/brainy.ts b/src/brainy.ts index 3b5a1c9a..a0f06931 100644 --- a/src/brainy.ts +++ b/src/brainy.ts @@ -196,6 +196,7 @@ import { isDeterministicEmbedMode } from './embeddings/deterministicEmbedMode.js import { GenerationConflictError, StoreInconsistentError } from './db/errors.js' import { BrainyError, GraphIndexNotReadyError, MetadataIndexNotReadyError, MigrationInProgressError, VectorIndexNotReadyError } from './errors/brainyError.js' import { assessIndexReadiness } from './utils/indexReadiness.js' +import { reconstructNounWrapper } from './db/factLog.js' import { readLogAuthority, runLogCompletenessOracle, @@ -8274,15 +8275,17 @@ export class Brainy implements BrainyInterface { for (const m of curable) { const raw = await this.storage.readNounRaw(m.id) if (raw.metadata === null && raw.vector === null) continue // vanished since the scan - // IDENTITY re-commit: preserve the stored vector-file wrapper AS-IS — - // the denormalized enumeration fields and the embedding floats ride - // through, because a backfill must never DEGRADE the row it cures - // (a skeleton rewrite would drop the row's floats and its enumerable - // fields, and a later log replay could only reproduce the metadata - // leg's hydration). The wrapper's floats sit nested under `vector` - // (canonical noun vector files hold the denormalized noun, not a - // bare array); adjacency legs stay in SaveNounOperation's - // placeholder shape (the vector index owns them). + // LAW-SHAPE RE-COMMIT: rewrite canonical as EXACTLY the wrapper the + // log's reconstruction produces (the hydration law: denormalized + // enumeration fields derived from the metadata leg + the embedding + // floats). This is what makes the backfill actually CURE + // state-differs drift: rows written before the hydration law carry + // denormalized copies that disagree with their own metadata leg, and + // an as-is identity re-commit preserves that drift forever — the + // oracle re-flags it every pass and existing brains never flip. The + // metadata leg is the authority (denormalized fields are its + // projections, per the field-addressing law); nothing degrades: the + // floats ride through, adjacency residue has its own rebuild path. const wrapper = raw.vector !== null && typeof raw.vector === 'object' && !Array.isArray(raw.vector) ? (raw.vector as Record) @@ -8292,16 +8295,21 @@ export class Brainy implements BrainyInterface { : Array.isArray(wrapper?.vector) ? (wrapper!.vector as number[]) : [] + const lawWrapper = reconstructNounWrapper(m.id, raw.metadata, vector) + const priorRaw = { metadata: raw.metadata, vector: raw.vector } await this.persistSingleOp({ nouns: [m.id] }, async (tx) => { - tx.addOperation( - new SaveNounOperation(this.storage, { - ...(wrapper ?? {}), - id: m.id, - vector, - connections: new Map(), - level: typeof wrapper?.level === 'number' ? (wrapper.level as number) : 0 - } as HNSWNoun) - ) + tx.addOperation({ + name: 'BaselineLawShapeRewrite', + execute: async () => { + await this.storage.writeNounRaw(m.id, { + metadata: raw.metadata, + vector: lawWrapper + }) + return async () => { + await this.storage.writeNounRaw(m.id, priorRaw) + } + } + }) }) } const next = await this.verifyLogAuthority() diff --git a/src/db/factLog.ts b/src/db/factLog.ts index 22fc8aa0..82949fb6 100644 --- a/src/db/factLog.ts +++ b/src/db/factLog.ts @@ -423,7 +423,7 @@ function reconstructTimestamp(value: unknown): number | undefined { * wrapper digests byte-equal to canonical. A drifted denormalized copy * surfaces as an oracle `state-differs` — named, never silently absorbed. */ -function reconstructNounWrapper( +export function reconstructNounWrapper( id: string, metadataLeg: unknown, floats: number[] diff --git a/tests/integration/adopt-drift-cure.test.ts b/tests/integration/adopt-drift-cure.test.ts new file mode 100644 index 00000000..fb154574 --- /dev/null +++ b/tests/integration/adopt-drift-cure.test.ts @@ -0,0 +1,107 @@ +/** + * @module tests/integration/adopt-drift-cure + * @description THE DRIFT-CURING BACKFILL — the actual completion of the + * default-flip ruling: existing brains whose canonical wrappers carry + * pre-hydration-law drift (denormalized fields disagreeing with their own + * metadata leg — the real depot-brain shape, uuid-v7 rows from the 9.0 era) + * must ADOPT AUTOMATICALLY: the backfill rewrites canonical in the law + * shape (metadata leg = the authority; floats preserved), the oracle then + * verifies the rewrite before flipping. Same safety, zero operator chores. + * Log-ahead divergences still refuse as before. + */ +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' + +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 }) +}) + +type RawBox = { + storage: { + readNounRaw(id: string): Promise<{ metadata: unknown; vector: unknown }> + writeNounRaw(id: string, r: { metadata: unknown; vector: unknown }): Promise + } +} + +describe('adoption cures hydration-law drift automatically', () => { + it('a drifted wrapper (stale denormalized fields) adopts green with floats preserved', async () => { + const dir = mkdtempSync(join(tmpdir(), 'brainy-drift-cure-')) + dirs.push(dir) + const brain = new Brainy({ + storage: { type: 'filesystem', path: dir }, + requireSubtype: false, + logAuthority: 'defer' + }) + await brain.init() + brains.push(brain) + const id = await brain.add({ + data: 'early-era row with drift', + type: NounType.Document, + metadata: { k: 1 } + }) + await brain.flush() + const before = await brain.get(id, { includeVectors: true }) + const floats = [...(before!.vector as number[])] + expect(floats.length).toBeGreaterThan(0) + + // Manufacture the depot shape: the stored wrapper's denormalized fields + // disagree with the metadata leg (pre-hydration-law drift) — an as-is + // identity re-commit preserves this forever; the law-shape rewrite cures it. + const storage = (brain as unknown as RawBox).storage + const raw = await storage.readNounRaw(id) + const wrapper = raw.vector as Record + await storage.writeNounRaw(id, { + metadata: raw.metadata, + vector: { + ...wrapper, + noun: 'thing', // stale denormalized type (metadata leg says document) + legacyField: 'pre-law residue', + createdAt: '1999-01-01T00:00:00.000Z' + } + }) + // Confirm the drift is oracle-visible before the cure. + expect((await brain.verifyLogAuthority()).verdict, 'drift detected').toBe('red') + + // THE PIN: adoption cures it without any operator step. + const report = await brain.adoptLogAuthority() + expect(report.verdict).toBe('green') + expect(brain.logAuthority().authority).toBe('log') + + // Nothing degraded: floats byte-identical, metadata intact, row serves. + const after = await brain.get(id, { includeVectors: true }) + expect(after!.vector as number[], 'floats preserved through the cure').toEqual(floats) + expect((after!.metadata as { k: number }).k).toBe(1) + expect((await brain.find({ where: { k: 1 }, limit: 5 })).map((r) => r.id)).toContain(id) + }, 120000) + + it('log-ahead divergences still refuse — the backfill never papers over a log the witness denies', async () => { + const dir = mkdtempSync(join(tmpdir(), 'brainy-logahead-')) + dirs.push(dir) + const brain = new Brainy({ + storage: { type: 'filesystem', path: dir }, + requireSubtype: false, + logAuthority: 'defer' + }) + await brain.init() + brains.push(brain) + const id = await brain.add({ data: 'row', type: NounType.Document, metadata: { k: 1 } }) + await brain.flush() + + // Log-ahead shape: canonical loses the record while the log still + // claims it live (log-live-canonical-absent — NOT curable by baseline). + const storage = (brain as unknown as RawBox).storage + await storage.writeNounRaw(id, { metadata: null, vector: null }) + + await expect(brain.adoptLogAuthority()).rejects.toThrow( + /log-ahead|witness denies|log claims/i + ) + expect(brain.logAuthority().authority).toBe('tree') + }, 120000) +})