@claude-flow/memory 3.0.0-alpha.16 → 3.0.0-alpha.18

package/dist/fts5.test.js

@@ -0,0 +1,144 @@
+/**
+ * Phase 5 — FTS5 keyword index (ADR-125)
+ *
+ * Verifies the FTS5 wiring on the two SQL backends:
+ * - SqlJsBackend  (sql.js — WASM, ships FTS5 since 1.10)
+ * - SQLiteBackend (better-sqlite3 — bundles FTS5 since 11.x)
+ *
+ * The SQLiteBackend test is conditional: better-sqlite3 is an optional
+ * dependency. If it isn't installable in the current env, that test is
+ * skipped.
+ */
+import { describe, it, expect } from 'vitest';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { SqlJsBackend } from './sqljs-backend.js';
+import { createDefaultEntry } from './types.js';
+const require = createRequire(import.meta.url);
+/**
+ * Locate the local sql-wasm.wasm so vitest doesn't try to fetch it over HTTP.
+ * Returns null if sql.js isn't installed in this env (treated as a skip
+ * signal by the suite).
+ */
+function locateSqlWasm() {
+    try {
+        const sqljsPkg = require.resolve('sql.js/package.json');
+        const wasmPath = sqljsPkg.replace(/package\.json$/, 'dist/sql-wasm.wasm');
+        return existsSync(wasmPath) ? wasmPath : null;
+    }
+    catch {
+        return null;
+    }
+}
+const WASM_PATH = locateSqlWasm();
+async function newSqlJs() {
+    if (!WASM_PATH)
+        throw new Error('sql.js/dist/sql-wasm.wasm not found');
+    const backend = new SqlJsBackend({ databasePath: ':memory:', wasmPath: WASM_PATH });
+    await backend.initialize();
+    return backend;
+}
+describe('Phase 5 — SqlJsBackend FTS5', () => {
+    it('searchKeyword returns matching entries for an FTS phrase', async () => {
+        const backend = await newSqlJs();
+        const phrases = [
+            'authentication patterns for OAuth flow',
+            'database migrations and schema changes',
+            'rate limiting and throttling middleware',
+            'caching strategies for distributed systems',
+            'jwt token validation security',
+        ];
+        for (let i = 0; i < 20; i++) {
+            const phrase = phrases[i % phrases.length];
+            const entry = createDefaultEntry({ key: `k-${i}`, content: `${phrase} ${i}` });
+            await backend.store(entry);
+        }
+        const results = await backend.searchKeyword('authentication patterns', 10);
+        expect(results.length).toBeGreaterThan(0);
+        for (const r of results) {
+            const c = r.entry.content.toLowerCase();
+            // At least one of the two query tokens should appear
+            expect(c.includes('authentication') || c.includes('patterns')).toBe(true);
+        }
+        await backend.shutdown();
+    });
+    it('searchKeyword does not return a deleted entry', async () => {
+        const backend = await newSqlJs();
+        const entry = createDefaultEntry({ key: 'doomed', content: 'unique-marker-phrase' });
+        await backend.store(entry);
+        let results = await backend.searchKeyword('unique-marker-phrase', 5);
+        expect(results.length).toBe(1);
+        await backend.delete(entry.id);
+        results = await backend.searchKeyword('unique-marker-phrase', 5);
+        expect(results.length).toBe(0);
+        await backend.shutdown();
+    });
+    it('searchKeyword reflects content updates', async () => {
+        const backend = await newSqlJs();
+        const entry = createDefaultEntry({ key: 'updatable', content: 'original phrase about apples' });
+        await backend.store(entry);
+        let results = await backend.searchKeyword('apples', 5);
+        expect(results.length).toBe(1);
+        await backend.update(entry.id, { content: 'rewritten phrase about bananas' });
+        results = await backend.searchKeyword('apples', 5);
+        expect(results.length).toBe(0);
+        results = await backend.searchKeyword('bananas', 5);
+        expect(results.length).toBe(1);
+        await backend.shutdown();
+    });
+    it('searchKeyword returns [] for an empty query', async () => {
+        const backend = await newSqlJs();
+        const results = await backend.searchKeyword('   ', 5);
+        expect(results).toEqual([]);
+        await backend.shutdown();
+    });
+});
+// Conditionally run the SQLiteBackend tests — better-sqlite3 is an optional
+// dependency, so probe for it first.
+async function probeBetterSqlite3() {
+    try {
+        await import('better-sqlite3');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+describe('Phase 5 — SQLiteBackend FTS5 (better-sqlite3)', async () => {
+    const hasBetterSqlite3 = await probeBetterSqlite3();
+    const maybeIt = hasBetterSqlite3 ? it : it.skip;
+    maybeIt('searchKeyword returns matching entries with FTS5 ranking', async () => {
+        const { SQLiteBackend } = await import('./sqlite-backend.js');
+        const backend = new SQLiteBackend({ databasePath: ':memory:' });
+        await backend.initialize();
+        for (let i = 0; i < 20; i++) {
+            const entry = createDefaultEntry({
+                key: `k-${i}`,
+                content: i % 2 === 0
+                    ? `authentication patterns OAuth ${i}`
+                    : `database indexing strategies ${i}`,
+            });
+            await backend.store(entry);
+        }
+        const results = await backend.searchKeyword('authentication', 10);
+        expect(results.length).toBeGreaterThan(0);
+        for (const r of results) {
+            expect(r.entry.content.toLowerCase()).toContain('authentication');
+        }
+        await backend.shutdown();
+    });
+    maybeIt('searchKeyword stops finding entries after delete', async () => {
+        const { SQLiteBackend } = await import('./sqlite-backend.js');
+        const backend = new SQLiteBackend({ databasePath: ':memory:' });
+        await backend.initialize();
+        const entry = createDefaultEntry({ key: 'doomed', content: 'unique-marker' });
+        await backend.store(entry);
+        let results = await backend.searchKeyword('unique-marker', 5);
+        expect(results.length).toBe(1);
+        await backend.delete(entry.id);
+        results = await backend.searchKeyword('unique-marker', 5);
+        expect(results.length).toBe(0);
+        await backend.shutdown();
+    });
+});
+//# sourceMappingURL=fts5.test.js.map

package/dist/fts5.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fts5.test.js","sourceRoot":"","sources":["../src/fts5.test.ts"],"names":[],"mappings":"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"}

package/dist/graceful-retrieval.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Phase 5 — Graceful retrieval degradation (ADR-125)
+ *
+ * Verifies:
+ * - `MemoryService.semanticSearch('foo')` with NO embedder configured falls
+ *   back to FTS / keyword search results without throwing AND emits
+ *   `health:embedder = { status: 'degraded' }` (Acceptance Criterion #5).
+ * - Same fallback when the embedder is configured but throws on call.
+ * - `hybridSearch` controller fuses dense + sparse arms via RRF + MMR and
+ *   returns non-empty results with a mean score at least as high as either
+ *   pure arm.
+ */
+export {};
+//# sourceMappingURL=graceful-retrieval.test.d.ts.map

package/dist/graceful-retrieval.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graceful-retrieval.test.d.ts","sourceRoot":"","sources":["../src/graceful-retrieval.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/graceful-retrieval.test.js

@@ -0,0 +1,144 @@
+/**
+ * Phase 5 — Graceful retrieval degradation (ADR-125)
+ *
+ * Verifies:
+ * - `MemoryService.semanticSearch('foo')` with NO embedder configured falls
+ *   back to FTS / keyword search results without throwing AND emits
+ *   `health:embedder = { status: 'degraded' }` (Acceptance Criterion #5).
+ * - Same fallback when the embedder is configured but throws on call.
+ * - `hybridSearch` controller fuses dense + sparse arms via RRF + MMR and
+ *   returns non-empty results with a mean score at least as high as either
+ *   pure arm.
+ */
+import { describe, it, expect } from 'vitest';
+import { MemoryService } from './index.js';
+import { ControllerRegistry } from './controller-registry.js';
+import { createDefaultEntry } from './types.js';
+async function newSvc(opts = {}) {
+    const svc = new MemoryService({
+        dimensions: 8,
+        persistenceEnabled: false,
+        snapshotInterval: 0,
+        ...opts,
+    });
+    await svc.initialize();
+    return svc;
+}
+function randomVec(dim, seed) {
+    const out = new Float32Array(dim);
+    let s = seed | 0 || 1;
+    for (let i = 0; i < dim; i++) {
+        s ^= s << 13;
+        s ^= s >>> 17;
+        s ^= s << 5;
+        out[i] = (s | 0) / 2 ** 31;
+    }
+    return out;
+}
+describe('Phase 5 — semanticSearch falls back without embedder', () => {
+    it('Acceptance Criterion #5 — no embedder → keyword results, no throw', async () => {
+        const svc = await newSvc(); // no embeddingGenerator
+        for (let i = 0; i < 10; i++) {
+            const entry = createDefaultEntry({
+                key: `k-${i}`,
+                content: i % 2 === 0
+                    ? `authentication patterns for OAuth ${i}`
+                    : `database migration schema ${i}`,
+            });
+            await svc.store(entry);
+        }
+        let degraded = null;
+        svc.getAdapter().on('health:embedder', (ev) => { degraded = ev; });
+        const results = await svc.semanticSearch('authentication', 5);
+        expect(Array.isArray(results)).toBe(true);
+        expect(results.length).toBeGreaterThan(0);
+        // Every result should match the keyword
+        for (const r of results) {
+            expect(r.entry.content.toLowerCase()).toContain('authentication');
+        }
+        expect(degraded).not.toBeNull();
+        expect(degraded.status).toBe('degraded');
+        await svc.close();
+    });
+    it('embedder that throws → degraded event + keyword fallback', async () => {
+        // Build a service where the embedder ALWAYS throws on read paths only.
+        // We bypass the throw on write by pre-populating an embedding on each
+        // stored entry — this mirrors real-world failure modes where indexing
+        // happened with a healthy embedder but the embedder later goes down.
+        const svc = await newSvc({
+            embeddingGenerator: async () => {
+                throw new Error('embedding service unavailable');
+            },
+        });
+        for (let i = 0; i < 5; i++) {
+            const entry = createDefaultEntry({
+                key: `t-${i}`,
+                content: `token validation ${i}`,
+            });
+            entry.embedding = randomVec(8, i + 1); // pre-set so store() doesn't call embedder
+            await svc.store(entry);
+        }
+        let degraded = null;
+        svc.getAdapter().on('health:embedder', (ev) => { degraded = ev; });
+        const results = await svc.semanticSearch('token validation', 5);
+        expect(results.length).toBeGreaterThan(0);
+        expect(degraded?.status).toBe('degraded');
+        expect(degraded?.reason).toContain('embedding service unavailable');
+        await svc.close();
+    });
+});
+describe('Phase 5 — hybridSearch controller (RRF + MMR)', () => {
+    it('fuses dense + sparse arms into a non-empty result', async () => {
+        // Use a deterministic embedder so the dense arm is reproducible
+        const dim = 8;
+        const svc = new MemoryService({
+            dimensions: dim,
+            persistenceEnabled: false,
+            snapshotInterval: 0,
+            embeddingGenerator: async (text) => randomVec(dim, hashStr(text)),
+        });
+        await svc.initialize();
+        // 50 entries: 25 about "authentication", 25 about "indexing"
+        for (let i = 0; i < 25; i++) {
+            const entry = createDefaultEntry({
+                key: `auth-${i}`,
+                content: `authentication and authorization patterns ${i}`,
+            });
+            entry.embedding = randomVec(dim, hashStr(entry.content));
+            await svc.store(entry);
+        }
+        for (let i = 0; i < 25; i++) {
+            const entry = createDefaultEntry({
+                key: `idx-${i}`,
+                content: `database indexing strategies ${i}`,
+            });
+            entry.embedding = randomVec(dim, hashStr(entry.content));
+            await svc.store(entry);
+        }
+        const registry = new ControllerRegistry();
+        await registry.initialize({ memoryService: svc });
+        const hybrid = registry.get('hybridSearch');
+        expect(hybrid).toBeTruthy();
+        expect(hybrid.source).toBe('hybrid-rrf-mmr');
+        const results = await hybrid.search('authentication', { limit: 10 });
+        expect(results.length).toBeGreaterThan(0);
+        // Mean RRF-fused score should be > 0
+        const mean = results.reduce((acc, r) => acc + r.score, 0) / results.length;
+        expect(mean).toBeGreaterThan(0);
+        // Verify hybrid surfaces relevant entries from BOTH arms by checking
+        // that >=1 result mentions "authentication" (keyword arm signal).
+        const authMatches = results.filter((r) => r.entry.content.toLowerCase().includes('authentication'));
+        expect(authMatches.length).toBeGreaterThan(0);
+        // Hybrid should return up to `limit` entries (10 here, given 50 stored).
+        expect(results.length).toBeLessThanOrEqual(10);
+        await registry.shutdown();
+        await svc.close();
+    });
+});
+function hashStr(s) {
+    let h = 0;
+    for (let i = 0; i < s.length; i++)
+        h = (h * 31 + s.charCodeAt(i)) | 0;
+    return Math.abs(h) + 1;
+}
+//# sourceMappingURL=graceful-retrieval.test.js.map

package/dist/graceful-retrieval.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graceful-retrieval.test.js","sourceRoot":"","sources":["../src/graceful-retrieval.test.ts"],"names":[],"mappings":"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"}

package/dist/hnsw-index.d.ts

@@ -75,6 +75,57 @@ export declare class HNSWIndex extends EventEmitter {
      * Get the number of vectors in the index
      */
     get size(): number;
+    /**
+     * Read-only view of the resolved HNSW config (dimensions, M, etc.).
+     * Used by {@link MemoryConsolidator.compactHnsw} to rebuild the index with
+     * matching parameters.
+     */
+    getConfig(): Readonly<HNSWConfig>;
+    /**
+     * Magic header for serialized HNSW snapshots.
+     * Format: "HNSW" + version byte (0x01).
+     */
+    static readonly SERIALIZATION_MAGIC: Buffer<ArrayBuffer>;
+    /**
+     * Serialize the index to a binary buffer.
+     *
+     * Layout (all integers big-endian):
+     * - 5 bytes:  magic header "HNSW" + version (0x01)
+     * - 4 bytes:  dimensions (uint32)
+     * - 4 bytes:  M (uint32)
+     * - 4 bytes:  efConstruction (uint32)
+     * - 4 bytes:  metric length (uint32) + metric utf-8 bytes
+     * - 4 bytes:  maxLevel (uint32)
+     * - 4 bytes:  entryPoint length (uint32) + entryPoint utf-8 bytes (0 = null)
+     * - 4 bytes:  node count (uint32)
+     * - per node:
+     *   - 4 bytes id length + id utf-8 bytes
+     *   - 4 bytes level
+     *   - 4 bytes vector length (in floats) + vector bytes (Float32, little-endian native)
+     *   - 1 byte  hasNormalized (0/1)
+     *   - if hasNormalized: 4 bytes normalized length + normalized bytes
+     *   - 4 bytes connection-level count
+     *   - per level:
+     *     - 4 bytes layer index
+     *     - 4 bytes neighbor count
+     *     - per neighbor: 4 bytes id length + id utf-8 bytes
+     */
+    serialize(): Buffer;
+    /**
+     * Deserialize an HNSW index from a buffer produced by {@link serialize}.
+     *
+     * Throws on magic-header mismatch, version mismatch, or truncated input.
+     */
+    static deserialize(buf: Buffer): HNSWIndex;
+    private encodeLengthPrefixedString;
+    private encodeFloat32Array;
+    /**
+     * Remove a point from the index — alias for {@link removePoint}.
+     *
+     * Added by ADR-125 Phase 4 so {@link MemoryConsolidator} has a stable
+     * synchronous-shaped API to call. Internally delegates to {@link removePoint}.
+     */
+    remove(id: string): Promise<boolean>;
     private mergeConfig;
     private getRandomLevel;
     private insertNode;

package/dist/hnsw-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hnsw-index.d.ts","sourceRoot":"","sources":["../src/hnsw-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAEL,UAAU,EACV,SAAS,EAMV,MAAM,YAAY,CAAC;AAwLpB;;;;;;;GAOG;AACH,qBAAa,SAAU,SAAQ,YAAY;IACzC,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,SAAS,CAAS;IAG1B,OAAO,CAAC,KAAK,CAYX;IAGF,OAAO,CAAC,SAAS,CAA0B;gBAE/B,MAAM,GAAE,OAAO,CAAC,UAAU,CAAM;IAU5C;;OAEG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAwD/D;;OAEG;IACG,MAAM,CACV,KAAK,EAAE,YAAY,EACnB,CAAC,EAAE,MAAM,EACT,EAAE,CAAC,EAAE,MAAM,GACV,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAqEnD;;OAEG;IACG,iBAAiB,CACrB,KAAK,EAAE,YAAY,EACnB,CAAC,EAAE,MAAM,EACT,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,EAC/B,EAAE,CAAC,EAAE,MAAM,GACV,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAUnD;;OAEG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA6C/C;;OAEG;IACG,OAAO,CACX,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,CAAC,GACnD,OAAO,CAAC,IAAI,CAAC;IAmBhB;;OAEG;IACH,QAAQ,IAAI,SAAS;IAqBrB;;OAEG;IACH,KAAK,IAAI,IAAI;IAab;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAID,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,cAAc;YAQR,UAAU;YAkEV,WAAW;IA2DzB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAgE5B,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,gBAAgB;IA6BxB,OAAO,CAAC,QAAQ;IAehB,OAAO,CAAC,cAAc;IAetB;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;IAUhC;;OAEG;IACH,OAAO,CAAC,eAAe;IAkBvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkBzB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,iBAAiB;CAO1B;AAqTD,eAAe,SAAS,CAAC"}
+{"version":3,"file":"hnsw-index.d.ts","sourceRoot":"","sources":["../src/hnsw-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAEL,UAAU,EACV,SAAS,EAMV,MAAM,YAAY,CAAC;AAwLpB;;;;;;;GAOG;AACH,qBAAa,SAAU,SAAQ,YAAY;IACzC,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,SAAS,CAAS;IAG1B,OAAO,CAAC,KAAK,CAYX;IAGF,OAAO,CAAC,SAAS,CAA0B;gBAE/B,MAAM,GAAE,OAAO,CAAC,UAAU,CAAM;IAU5C;;OAEG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAwD/D;;OAEG;IACG,MAAM,CACV,KAAK,EAAE,YAAY,EACnB,CAAC,EAAE,MAAM,EACT,EAAE,CAAC,EAAE,MAAM,GACV,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAqEnD;;OAEG;IACG,iBAAiB,CACrB,KAAK,EAAE,YAAY,EACnB,CAAC,EAAE,MAAM,EACT,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,EAC/B,EAAE,CAAC,EAAE,MAAM,GACV,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAUnD;;OAEG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA6C/C;;OAEG;IACG,OAAO,CACX,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,CAAC,GACnD,OAAO,CAAC,IAAI,CAAC;IAmBhB;;OAEG;IACH,QAAQ,IAAI,SAAS;IAqBrB;;OAEG;IACH,KAAK,IAAI,IAAI;IAab;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;OAIG;IACH,SAAS,IAAI,QAAQ,CAAC,UAAU,CAAC;IAMjC;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,mBAAmB,sBAA+C;IAElF;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,SAAS,IAAI,MAAM;IAsDnB;;;;OAIG;IACH,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS;IAmF1C,OAAO,CAAC,0BAA0B;IAQlC,OAAO,CAAC,kBAAkB;IAO1B;;;;;OAKG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAM1C,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,cAAc;YAQR,UAAU;YAkEV,WAAW;IA2DzB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAgE5B,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,gBAAgB;IA6BxB,OAAO,CAAC,QAAQ;IAehB,OAAO,CAAC,cAAc;IAetB;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;IAUhC;;OAEG;IACH,OAAO,CAAC,eAAe;IAkBvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkBzB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,iBAAiB;CAO1B;AAiWD,eAAe,SAAS,CAAC"}

package/dist/hnsw-index.js

@@ -395,6 +395,192 @@ export class HNSWIndex extends EventEmitter {
     get size() {
         return this.nodes.size;
     }
+    /**
+     * Read-only view of the resolved HNSW config (dimensions, M, etc.).
+     * Used by {@link MemoryConsolidator.compactHnsw} to rebuild the index with
+     * matching parameters.
+     */
+    getConfig() {
+        return this.config;
+    }
+    // ===== Persistence (ADR-125 Phase 3) =====
+    /**
+     * Magic header for serialized HNSW snapshots.
+     * Format: "HNSW" + version byte (0x01).
+     */
+    static SERIALIZATION_MAGIC = Buffer.from([0x48, 0x4e, 0x53, 0x57, 0x01]);
+    /**
+     * Serialize the index to a binary buffer.
+     *
+     * Layout (all integers big-endian):
+     * - 5 bytes:  magic header "HNSW" + version (0x01)
+     * - 4 bytes:  dimensions (uint32)
+     * - 4 bytes:  M (uint32)
+     * - 4 bytes:  efConstruction (uint32)
+     * - 4 bytes:  metric length (uint32) + metric utf-8 bytes
+     * - 4 bytes:  maxLevel (uint32)
+     * - 4 bytes:  entryPoint length (uint32) + entryPoint utf-8 bytes (0 = null)
+     * - 4 bytes:  node count (uint32)
+     * - per node:
+     *   - 4 bytes id length + id utf-8 bytes
+     *   - 4 bytes level
+     *   - 4 bytes vector length (in floats) + vector bytes (Float32, little-endian native)
+     *   - 1 byte  hasNormalized (0/1)
+     *   - if hasNormalized: 4 bytes normalized length + normalized bytes
+     *   - 4 bytes connection-level count
+     *   - per level:
+     *     - 4 bytes layer index
+     *     - 4 bytes neighbor count
+     *     - per neighbor: 4 bytes id length + id utf-8 bytes
+     */
+    serialize() {
+        const chunks = [];
+        chunks.push(HNSWIndex.SERIALIZATION_MAGIC);
+        // Config header
+        const header = Buffer.alloc(16);
+        header.writeUInt32BE(this.config.dimensions, 0);
+        header.writeUInt32BE(this.config.M, 4);
+        header.writeUInt32BE(this.config.efConstruction, 8);
+        header.writeUInt32BE(this.maxLevel, 12);
+        chunks.push(header);
+        chunks.push(this.encodeLengthPrefixedString(this.config.metric));
+        chunks.push(this.encodeLengthPrefixedString(this.entryPoint ?? ''));
+        const nodeCountBuf = Buffer.alloc(4);
+        nodeCountBuf.writeUInt32BE(this.nodes.size, 0);
+        chunks.push(nodeCountBuf);
+        for (const [id, node] of this.nodes) {
+            chunks.push(this.encodeLengthPrefixedString(id));
+            const meta = Buffer.alloc(4);
+            meta.writeUInt32BE(node.level, 0);
+            chunks.push(meta);
+            chunks.push(this.encodeFloat32Array(node.vector));
+            if (node.normalizedVector) {
+                chunks.push(Buffer.from([1]));
+                chunks.push(this.encodeFloat32Array(node.normalizedVector));
+            }
+            else {
+                chunks.push(Buffer.from([0]));
+            }
+            const levels = [...node.connections.entries()];
+            const lvlCountBuf = Buffer.alloc(4);
+            lvlCountBuf.writeUInt32BE(levels.length, 0);
+            chunks.push(lvlCountBuf);
+            for (const [layer, neighbors] of levels) {
+                const layerBuf = Buffer.alloc(8);
+                layerBuf.writeUInt32BE(layer, 0);
+                layerBuf.writeUInt32BE(neighbors.size, 4);
+                chunks.push(layerBuf);
+                for (const neighborId of neighbors) {
+                    chunks.push(this.encodeLengthPrefixedString(neighborId));
+                }
+            }
+        }
+        return Buffer.concat(chunks);
+    }
+    /**
+     * Deserialize an HNSW index from a buffer produced by {@link serialize}.
+     *
+     * Throws on magic-header mismatch, version mismatch, or truncated input.
+     */
+    static deserialize(buf) {
+        if (buf.length < HNSWIndex.SERIALIZATION_MAGIC.length) {
+            throw new Error('HNSWIndex.deserialize: buffer too short for magic header');
+        }
+        for (let i = 0; i < HNSWIndex.SERIALIZATION_MAGIC.length; i++) {
+            if (buf[i] !== HNSWIndex.SERIALIZATION_MAGIC[i]) {
+                throw new Error(`HNSWIndex.deserialize: magic header mismatch at byte ${i} (got 0x${buf[i].toString(16)}, expected 0x${HNSWIndex.SERIALIZATION_MAGIC[i].toString(16)})`);
+            }
+        }
+        let offset = HNSWIndex.SERIALIZATION_MAGIC.length;
+        const dimensions = buf.readUInt32BE(offset);
+        offset += 4;
+        const M = buf.readUInt32BE(offset);
+        offset += 4;
+        const efConstruction = buf.readUInt32BE(offset);
+        offset += 4;
+        const maxLevel = buf.readUInt32BE(offset);
+        offset += 4;
+        const metricRead = readLengthPrefixedString(buf, offset);
+        offset = metricRead.offset;
+        const metric = metricRead.value;
+        const entryRead = readLengthPrefixedString(buf, offset);
+        offset = entryRead.offset;
+        const entryPoint = entryRead.value === '' ? null : entryRead.value;
+        const nodeCount = buf.readUInt32BE(offset);
+        offset += 4;
+        const index = new HNSWIndex({
+            dimensions,
+            M,
+            efConstruction,
+            metric,
+        });
+        index.maxLevel = maxLevel;
+        index.entryPoint = entryPoint;
+        for (let n = 0; n < nodeCount; n++) {
+            const idRead = readLengthPrefixedString(buf, offset);
+            offset = idRead.offset;
+            const id = idRead.value;
+            const level = buf.readUInt32BE(offset);
+            offset += 4;
+            const vecRead = readFloat32Array(buf, offset);
+            offset = vecRead.offset;
+            const vector = vecRead.value;
+            const hasNormalized = buf[offset];
+            offset += 1;
+            let normalizedVector = null;
+            if (hasNormalized) {
+                const normRead = readFloat32Array(buf, offset);
+                offset = normRead.offset;
+                normalizedVector = normRead.value;
+            }
+            const lvlCount = buf.readUInt32BE(offset);
+            offset += 4;
+            const connections = new Map();
+            for (let l = 0; l < lvlCount; l++) {
+                const layer = buf.readUInt32BE(offset);
+                offset += 4;
+                const neighborCount = buf.readUInt32BE(offset);
+                offset += 4;
+                const neighbors = new Set();
+                for (let k = 0; k < neighborCount; k++) {
+                    const neighborRead = readLengthPrefixedString(buf, offset);
+                    offset = neighborRead.offset;
+                    neighbors.add(neighborRead.value);
+                }
+                connections.set(layer, neighbors);
+            }
+            index.nodes.set(id, {
+                id,
+                vector,
+                normalizedVector,
+                connections,
+                level,
+            });
+        }
+        return index;
+    }
+    encodeLengthPrefixedString(s) {
+        const strBuf = Buffer.from(s, 'utf-8');
+        const out = Buffer.alloc(4 + strBuf.length);
+        out.writeUInt32BE(strBuf.length, 0);
+        strBuf.copy(out, 4);
+        return out;
+    }
+    encodeFloat32Array(arr) {
+        const lenBuf = Buffer.alloc(4);
+        lenBuf.writeUInt32BE(arr.length, 0);
+        const dataBuf = Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength);
+        return Buffer.concat([lenBuf, dataBuf]);
+    }
+    /**
+     * Remove a point from the index — alias for {@link removePoint}.
+     *
+     * Added by ADR-125 Phase 4 so {@link MemoryConsolidator} has a stable
+     * synchronous-shaped API to call. Internally delegates to {@link removePoint}.
+     */
+    async remove(id) {
+        return this.removePoint(id);
+    }
     // ===== Private Methods =====
     mergeConfig(config) {
         return {
@@ -944,5 +1130,36 @@ class Quantizer {
         return this.codebooks;
     }
 }
+// ===== Persistence Helpers (ADR-125 Phase 3) =====
+function readLengthPrefixedString(buf, offset) {
+    if (offset + 4 > buf.length) {
+        throw new Error(`HNSWIndex.deserialize: truncated string length at offset ${offset}`);
+    }
+    const len = buf.readUInt32BE(offset);
+    const start = offset + 4;
+    const end = start + len;
+    if (end > buf.length) {
+        throw new Error(`HNSWIndex.deserialize: truncated string payload at offset ${offset} (needed ${len} bytes, have ${buf.length - start})`);
+    }
+    const value = buf.toString('utf-8', start, end);
+    return { value, offset: end };
+}
+function readFloat32Array(buf, offset) {
+    if (offset + 4 > buf.length) {
+        throw new Error(`HNSWIndex.deserialize: truncated array length at offset ${offset}`);
+    }
+    const floatCount = buf.readUInt32BE(offset);
+    const start = offset + 4;
+    const byteLen = floatCount * 4;
+    const end = start + byteLen;
+    if (end > buf.length) {
+        throw new Error(`HNSWIndex.deserialize: truncated array payload at offset ${offset} (needed ${byteLen} bytes, have ${buf.length - start})`);
+    }
+    // Copy into a fresh ArrayBuffer so Float32Array isn't a view onto the original
+    // (de-aligned) Node Buffer pool.
+    const copy = new ArrayBuffer(byteLen);
+    new Uint8Array(copy).set(new Uint8Array(buf.buffer, buf.byteOffset + start, byteLen));
+    return { value: new Float32Array(copy), offset: end };
+}
 export default HNSWIndex;
 //# sourceMappingURL=hnsw-index.js.map