@fgv/ts-agent-memory 5.1.0-47 → 5.1.0-49

package/lib/test/unit/retrieve/retrievers.test.js

@@ -1,770 +0,0 @@
-"use strict";
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-require("@fgv/ts-utils-jest");
-const ts_utils_1 = require("@fgv/ts-utils");
-const index_1 = require("../../../index");
-/** A scope-qualified link-traversal seed for the retriever tests. */
-function et(id, scope = 'knowledge') {
-    return { scope: scope, id: id };
-}
-function makeEntry(spec) {
-    var _a, _b, _c, _d, _e;
-    const record = {
-        envelope: index_1.envelopeConverter
-            .convert(Object.assign(Object.assign({ id: spec.id, entityId: spec.id, kind: (_a = spec.kind) !== null && _a !== void 0 ? _a : 'knowledge', tags: (_b = spec.tags) !== null && _b !== void 0 ? _b : [], links: [], created: 0, updated: (_c = spec.updated) !== null && _c !== void 0 ? _c : 0, seq: (_d = spec.seq) !== null && _d !== void 0 ? _d : 0, contentHash: 'h' }, (spec.rank !== undefined ? { rank: spec.rank } : {})), { provenance: { source: 'agent' } }))
-            .orThrow(),
-        body: `body-${spec.id}`
-    };
-    return { scope: ((_e = spec.scope) !== null && _e !== void 0 ? _e : 'knowledge'), record };
-}
-function buildIndex(specs) {
-    const index = index_1.MemoryIndex.create().orThrow();
-    index.rebuild(specs.map(makeEntry)).orThrow();
-    return index;
-}
-function ids(records) {
-    return records.map((r) => r.envelope.id);
-}
-const knowledge = 'knowledge';
-describe('retrieve helpers', () => {
-    describe('guardRetrieverCapabilities', () => {
-        const noCaps = {
-            supportsSemanticRecall: false,
-            supportsTemporalQuery: false,
-            supportsLinkTraversal: false
-        };
-        test('passes when no unsupported capability is requested', () => {
-            expect((0, index_1.guardRetrieverCapabilities)({}, noCaps)).toSucceed();
-        });
-        test('fails loudly when semantic recall is requested but unsupported', () => {
-            expect((0, index_1.guardRetrieverCapabilities)({ semantic: 'q' }, noCaps)).toFailWith(/semantic recall requires a vector index; none configured/i);
-        });
-        test('fails loudly when an as-of query is requested but unsupported', () => {
-            expect((0, index_1.guardRetrieverCapabilities)({ asOf: 5 }, noCaps)).toFailWith(/temporal query requires temporal index; none configured/i);
-        });
-        test('names the kind in the temporal failure when present', () => {
-            expect((0, index_1.guardRetrieverCapabilities)({ asOf: 5, kind: knowledge }, noCaps)).toFailWith(/none configured for kind knowledge/i);
-        });
-        test('fails loudly when a link-traversal axis is requested but unsupported', () => {
-            expect((0, index_1.guardRetrieverCapabilities)({ linkedTo: et('x') }, noCaps)).toFailWith(/link traversal requires a backlink index; none configured/i);
-            expect((0, index_1.guardRetrieverCapabilities)({ linkedFrom: et('x') }, noCaps)).toFailWith(/link traversal requires/i);
-            expect((0, index_1.guardRetrieverCapabilities)({ hops: 2 }, noCaps)).toFailWith(/link traversal requires/i);
-        });
-        test('passes a link-traversal axis when the capability is supported', () => {
-            expect((0, index_1.guardRetrieverCapabilities)({ linkedTo: et('x') }, Object.assign(Object.assign({}, noCaps), { supportsLinkTraversal: true }))).toSucceed();
-        });
-    });
-    describe('limitRecords', () => {
-        const records = buildIndex([{ id: 'a' }, { id: 'b' }, { id: 'c' }])
-            .entries()
-            .map((e) => e.record);
-        test('returns all records when no limit is supplied', () => {
-            expect((0, index_1.limitRecords)(records)).toHaveLength(3);
-        });
-        test('truncates to the top-N for a positive limit', () => {
-            expect((0, index_1.limitRecords)(records, 2)).toHaveLength(2);
-        });
-        test('returns an empty array for a zero or negative limit', () => {
-            expect((0, index_1.limitRecords)(records, 0)).toEqual([]);
-            expect((0, index_1.limitRecords)(records, -1)).toEqual([]);
-        });
-        test('an absent offset is a no-op (byte-identical to today) — same reference returned', () => {
-            expect((0, index_1.limitRecords)(records, undefined, undefined)).toBe(records);
-            expect((0, index_1.limitRecords)(records, 2, undefined)).toHaveLength(2);
-            // A non-positive offset is guarded like a non-positive limit — no skip.
-            expect((0, index_1.limitRecords)(records, undefined, 0)).toBe(records);
-            expect(ids((0, index_1.limitRecords)(records, undefined, -5))).toEqual(['a', 'b', 'c']);
-        });
-        test('offset skips after ordering; { offset, limit } is a stable page window', () => {
-            expect(ids((0, index_1.limitRecords)(records, undefined, 1))).toEqual(['b', 'c']);
-            expect(ids((0, index_1.limitRecords)(records, 1, 1))).toEqual(['b']);
-            expect(ids((0, index_1.limitRecords)(records, 2, 1))).toEqual(['b', 'c']);
-        });
-        test('an offset past the end yields an empty page (never a throw)', () => {
-            expect((0, index_1.limitRecords)(records, undefined, 3)).toEqual([]);
-            expect((0, index_1.limitRecords)(records, 5, 99)).toEqual([]);
-        });
-        test('a non-positive limit still wins over an offset window', () => {
-            expect((0, index_1.limitRecords)(records, 0, 1)).toEqual([]);
-        });
-    });
-});
-describe('RecencyRetriever', () => {
-    test('reports all-false capabilities', () => {
-        const r = index_1.RecencyRetriever.create(buildIndex([])).orThrow();
-        expect(r.capabilities).toEqual({
-            supportsSemanticRecall: false,
-            supportsTemporalQuery: false,
-            supportsLinkTraversal: false
-        });
-    });
-    test('returns every record most-recently-updated first', async () => {
-        const r = index_1.RecencyRetriever.create(buildIndex([
-            { id: 'a', updated: 10 },
-            { id: 'b', updated: 30 },
-            { id: 'c', updated: 20 }
-        ])).orThrow();
-        expect(await r.retrieve({})).toSucceedAndSatisfy((records) => {
-            expect(ids(records)).toEqual(['b', 'c', 'a']);
-        });
-    });
-    test('breaks ties on seq descending', async () => {
-        const r = index_1.RecencyRetriever.create(buildIndex([
-            { id: 'a', updated: 10, seq: 1 },
-            { id: 'b', updated: 10, seq: 3 },
-            { id: 'c', updated: 10, seq: 2 }
-        ])).orThrow();
-        expect(await r.retrieve({})).toSucceedAndSatisfy((records) => {
-            expect(ids(records)).toEqual(['b', 'c', 'a']);
-        });
-    });
-    test('honors scope, kind, tag, predicate, and limit filters', async () => {
-        const index = buildIndex([
-            { id: 'a', scope: 'knowledge', kind: 'knowledge', tags: ['x'], updated: 50 },
-            { id: 'b', scope: 'knowledge', kind: 'knowledge', tags: ['y'], updated: 40 },
-            { id: 'c', scope: 'other', kind: 'knowledge', tags: ['x'], updated: 60 },
-            { id: 'd', scope: 'knowledge', kind: 'note', tags: ['x'], updated: 70 }
-        ]);
-        const r = index_1.RecencyRetriever.create(index).orThrow();
-        expect(await r.retrieve({
-            scope: 'knowledge',
-            kind: knowledge,
-            tag: 'x',
-            filter: (rec) => rec.envelope.id !== 'skip',
-            limit: 5
-        })).toSucceedAndSatisfy((records) => {
-            expect(ids(records)).toEqual(['a']);
-        });
-    });
-    test('limit truncates to the top-N after ordering', async () => {
-        const r = index_1.RecencyRetriever.create(buildIndex([
-            { id: 'a', updated: 10 },
-            { id: 'b', updated: 30 },
-            { id: 'c', updated: 20 }
-        ])).orThrow();
-        expect(await r.retrieve({ limit: 2 })).toSucceedAndSatisfy((records) => {
-            expect(ids(records)).toEqual(['b', 'c']);
-        });
-    });
-    test('degrades loudly on a semantic request', async () => {
-        const r = index_1.RecencyRetriever.create(buildIndex([{ id: 'a' }])).orThrow();
-        expect(await r.retrieve({ semantic: 'hello' })).toFailWith(/semantic recall requires a vector index/i);
-    });
-    test('degrades loudly on a link-traversal request', async () => {
-        const r = index_1.RecencyRetriever.create(buildIndex([{ id: 'a' }])).orThrow();
-        expect(await r.retrieve({ linkedTo: et('a') })).toFailWith(/link traversal requires/i);
-    });
-});
-describe('orderBy: rank axis', () => {
-    const a1 = makeEntry({ id: 'a', rank: 1, updated: 100, seq: 1 }).record;
-    const b3 = makeEntry({ id: 'b', rank: 3, updated: 100, seq: 2 }).record;
-    const c2 = makeEntry({ id: 'c', rank: 2, updated: 100, seq: 3 }).record;
-    const unranked = makeEntry({ id: 'z', updated: 999, seq: 4 }).record;
-    describe('rankCompare', () => {
-        test('orders by rank descending', () => {
-            expect([a1, b3, c2]
-                .slice()
-                .sort(index_1.rankCompare)
-                .map((r) => r.envelope.id)).toEqual(['b', 'c', 'a']);
-        });
-        test('places an absent-rank record last regardless of recency', () => {
-            // `unranked` has the newest `updated`, but an absent rank sorts after every ranked record.
-            expect([unranked, a1, b3]
-                .slice()
-                .sort(index_1.rankCompare)
-                .map((r) => r.envelope.id)).toEqual(['b', 'a', 'z']);
-            // Symmetric: absent on the left side of the compare too.
-            expect([a1, unranked]
-                .slice()
-                .sort(index_1.rankCompare)
-                .map((r) => r.envelope.id)).toEqual(['a', 'z']);
-        });
-        test('breaks an equal-rank tie by recency', () => {
-            const b3b = makeEntry({ id: 'b2', rank: 3, updated: 50, seq: 9 }).record;
-            // Equal rank 3 → newer `updated` (b3 at 100) first.
-            expect([b3b, b3]
-                .slice()
-                .sort(index_1.rankCompare)
-                .map((r) => r.envelope.id)).toEqual(['b', 'b2']);
-        });
-    });
-    describe('orderingCompare', () => {
-        test("returns recencyCompare for absent orderBy and 'recency'", () => {
-            expect((0, index_1.orderingCompare)()).toBe(index_1.recencyCompare);
-            expect((0, index_1.orderingCompare)('recency')).toBe(index_1.recencyCompare);
-        });
-        test("returns rankCompare for 'rank'", () => {
-            expect((0, index_1.orderingCompare)('rank')).toBe(index_1.rankCompare);
-        });
-    });
-    describe.each([
-        ['RecencyRetriever', (index) => index_1.RecencyRetriever.create(index).orThrow()],
-        ['TagRetriever', (index) => index_1.TagRetriever.create(index).orThrow()],
-        [
-            'StructuredFilterRetriever',
-            (index) => index_1.StructuredFilterRetriever.create(index).orThrow()
-        ]
-    ])('%s honors orderBy', (name, make) => {
-        // Tag / structured-filter need their axis present to return anything.
-        const axis = name === 'TagRetriever'
-            ? { tag: 'x' }
-            : name === 'StructuredFilterRetriever'
-                ? { filter: () => true }
-                : {};
-        function orderedIndex() {
-            return buildIndex([
-                { id: 'a', rank: 1, tags: ['x'], updated: 100, seq: 1 },
-                { id: 'b', rank: 3, tags: ['x'], updated: 100, seq: 2 },
-                { id: 'c', rank: 2, tags: ['x'], updated: 100, seq: 3 },
-                { id: 'z', tags: ['x'], updated: 999, seq: 4 }
-            ]);
-        }
-        test("orderBy 'rank' orders by rank descending, absent last", async () => {
-            const r = make(orderedIndex());
-            expect(await r.retrieve(Object.assign(Object.assign({}, axis), { orderBy: 'rank' }))).toSucceedAndSatisfy((records) => {
-                expect(ids(records)).toEqual(['b', 'c', 'a', 'z']);
-            });
-        });
-        test('orderBy absent is unchanged recency order', async () => {
-            const r = make(orderedIndex());
-            expect(await r.retrieve(Object.assign({}, axis))).toSucceedAndSatisfy((records) => {
-                // `z` has the newest `updated`; the rest tie on `updated` and break by
-                // seq descending (c=3, b=2, a=1) — recency order regardless of rank.
-                expect(ids(records)).toEqual(['z', 'c', 'b', 'a']);
-            });
-        });
-        test('rank ordering composes with { limit, offset } for a bounded top-M page', async () => {
-            const r = make(orderedIndex());
-            expect(await r.retrieve(Object.assign(Object.assign({}, axis), { orderBy: 'rank', limit: 1, offset: 1 }))).toSucceedAndSatisfy((records) => {
-                expect(ids(records)).toEqual(['c']);
-            });
-        });
-    });
-    test("HybridRetriever re-orders the merged set by rank for orderBy 'rank'", async () => {
-        const index = buildIndex([
-            { id: 'a', rank: 1, tags: ['x'], updated: 100, seq: 1 },
-            { id: 'b', rank: 3, tags: ['x'], updated: 100, seq: 2 },
-            { id: 'c', rank: 2, tags: ['x'], updated: 100, seq: 3 }
-        ]);
-        const hybrid = index_1.HybridRetriever.create([index_1.RecencyRetriever.create(index).orThrow(), index_1.TagRetriever.create(index).orThrow()], index_1.ScoreUnionMergeStrategy.create().orThrow()).orThrow();
-        expect(await hybrid.retrieve({ tag: 'x', orderBy: 'rank' })).toSucceedAndSatisfy((records) => {
-            // All three score 2 (surfaced by both children); orderBy rank re-sorts the merge.
-            expect(ids(records)).toEqual(['b', 'c', 'a']);
-        });
-    });
-    test("SemanticRetriever preserves vector-similarity order regardless of orderBy 'rank'", async () => {
-        const index = buildIndex([
-            { id: 'a', rank: 9, updated: 1 },
-            { id: 'b', rank: 1, updated: 1 }
-        ]);
-        const vectorIndex = {
-            add: (t) => Promise.resolve((0, ts_utils_1.succeed)(`ref-${t.id}`)),
-            remove: (t) => Promise.resolve((0, ts_utils_1.succeed)(t)),
-            query: () => Promise.resolve((0, ts_utils_1.succeed)([
-                { target: et('b'), score: 0.9 },
-                { target: et('a'), score: 0.5 }
-            ]))
-        };
-        const r = index_1.SemanticRetriever.create({
-            index,
-            backend: {
-                vectorIndex,
-                embedQuery: () => Promise.resolve((0, ts_utils_1.succeed)(Float32Array.from([0.1])))
-            }
-        }).orThrow();
-        // Even though `a` has the higher rank, semantic keeps the similarity order (b before a).
-        expect(await r.retrieve({ semantic: 'q', orderBy: 'rank' })).toSucceedAndSatisfy((records) => {
-            expect(ids(records)).toEqual(['b', 'a']);
-        });
-    });
-});
-describe('query axes: kinds (kind-set) and offset', () => {
-    function multiKindRetriever() {
-        return index_1.RecencyRetriever.create(buildIndex([
-            { id: 'k1', kind: 'knowledge', updated: 40 },
-            { id: 'n1', kind: 'note', updated: 30 },
-            { id: 'e1', kind: 'event', updated: 20 },
-            { id: 'k2', kind: 'knowledge', updated: 10 }
-        ])).orThrow();
-    }
-    describe('kinds', () => {
-        test("an absent kinds axis imposes no kind constraint (today's behavior)", async () => {
-            expect(await multiKindRetriever().retrieve({})).toSucceedAndSatisfy((records) => {
-                expect([...ids(records)].sort()).toEqual(['e1', 'k1', 'k2', 'n1']);
-            });
-        });
-        test('restricts to records in ANY of the listed kinds', async () => {
-            expect(await multiKindRetriever().retrieve({
-                kinds: ['knowledge', 'event']
-            })).toSucceedAndSatisfy((records) => {
-                expect([...ids(records)].sort()).toEqual(['e1', 'k1', 'k2']);
-            });
-        });
-        test('an explicit empty kinds array matches NOTHING (not match-all)', async () => {
-            expect(await multiKindRetriever().retrieve({ kinds: [] })).toSucceedWith([]);
-        });
-        test('kind and kinds compose as AND (kind must be a member of kinds)', async () => {
-            // kind=knowledge AND kinds includes knowledge → knowledge records only.
-            expect(await multiKindRetriever().retrieve({
-                kind: knowledge,
-                kinds: ['knowledge', 'note']
-            })).toSucceedAndSatisfy((records) => {
-                expect([...ids(records)].sort()).toEqual(['k1', 'k2']);
-            });
-            // kind=knowledge but kinds excludes knowledge → nothing can satisfy both.
-            expect(await multiKindRetriever().retrieve({
-                kind: knowledge,
-                kinds: ['note', 'event']
-            })).toSucceedWith([]);
-        });
-    });
-    describe('offset', () => {
-        function ordered() {
-            return index_1.RecencyRetriever.create(buildIndex([
-                { id: 'a', updated: 10 },
-                { id: 'b', updated: 40 },
-                { id: 'c', updated: 30 },
-                { id: 'd', updated: 20 }
-            ])).orThrow();
-        }
-        test('skips after ordering, forming a stable { offset, limit } page window', async () => {
-            // Recency order is [b, c, d, a].
-            expect(await ordered().retrieve({ offset: 1, limit: 2 })).toSucceedAndSatisfy((records) => {
-                expect(ids(records)).toEqual(['c', 'd']);
-            });
-        });
-        test('an absent offset is unchanged from today', async () => {
-            expect(await ordered().retrieve({ limit: 2 })).toSucceedAndSatisfy((records) => {
-                expect(ids(records)).toEqual(['b', 'c']);
-            });
-        });
-        test('an offset past the end yields an empty page', async () => {
-            expect(await ordered().retrieve({ offset: 99 })).toSucceedWith([]);
-        });
-        test('a negative offset does not slip into slice (treated as no skip)', async () => {
-            expect(await ordered().retrieve({ offset: -3, limit: 2 })).toSucceedAndSatisfy((records) => {
-                expect(ids(records)).toEqual(['b', 'c']);
-            });
-        });
-    });
-});
-/** A retriever with configurable capabilities that records the query it received. */
-class RecordingRetriever {
-    constructor(capabilities) {
-        this.capabilities = capabilities;
-    }
-    retrieve(query) {
-        this.lastQuery = query;
-        return Promise.resolve((0, ts_utils_1.succeed)([]));
-    }
-}
-describe('TagRetriever', () => {
-    test('returns records carrying the tag, recency-ordered', async () => {
-        const r = index_1.TagRetriever.create(buildIndex([
-            { id: 'a', tags: ['x'], updated: 10 },
-            { id: 'b', tags: ['x', 'y'], updated: 30 },
-            { id: 'c', tags: ['y'], updated: 20 }
-        ])).orThrow();
-        expect(await r.retrieve({ tag: 'x' })).toSucceedAndSatisfy((records) => {
-            expect(ids(records)).toEqual(['b', 'a']);
-        });
-    });
-    test('returns empty (not failure) when no tag is supplied', async () => {
-        const r = index_1.TagRetriever.create(buildIndex([{ id: 'a', tags: ['x'] }])).orThrow();
-        expect(await r.retrieve({})).toSucceedWith([]);
-    });
-    test('degrades loudly on a semantic request', async () => {
-        const r = index_1.TagRetriever.create(buildIndex([{ id: 'a', tags: ['x'] }])).orThrow();
-        expect(await r.retrieve({ tag: 'x', semantic: 'q' })).toFailWith(/semantic recall requires/i);
-    });
-});
-describe('StructuredFilterRetriever', () => {
-    test('applies the predicate over the scope/kind/tag pre-filter', async () => {
-        const r = index_1.StructuredFilterRetriever.create(buildIndex([
-            { id: 'keep-1', updated: 10 },
-            { id: 'drop-1', updated: 30 },
-            { id: 'keep-2', updated: 20 }
-        ])).orThrow();
-        expect(await r.retrieve({ filter: (rec) => rec.envelope.id.startsWith('keep') })).toSucceedAndSatisfy((records) => {
-            expect(ids(records)).toEqual(['keep-2', 'keep-1']);
-        });
-    });
-    test('returns empty (not failure) when no predicate is supplied', async () => {
-        const r = index_1.StructuredFilterRetriever.create(buildIndex([{ id: 'a' }])).orThrow();
-        expect(await r.retrieve({})).toSucceedWith([]);
-    });
-});
-/** A scripted in-memory vector index returning canned hits. */
-class FakeVectorIndex {
-    constructor(hits, failQuery = false) {
-        this._hits = hits;
-        this._failQuery = failQuery;
-    }
-    add(t) {
-        return Promise.resolve((0, ts_utils_1.succeed)(`ref-${t.id}`));
-    }
-    remove(t) {
-        return Promise.resolve((0, ts_utils_1.succeed)(t));
-    }
-    query(__vector, topK) {
-        this.lastTopK = topK;
-        return Promise.resolve(this._failQuery ? (0, ts_utils_1.fail)('vector backend down') : (0, ts_utils_1.succeed)(this._hits));
-    }
-}
-describe('SemanticRetriever', () => {
-    const okEmbed = () => Promise.resolve((0, ts_utils_1.succeed)(Float32Array.from([0.1, 0.2])));
-    test('reports supportsSemanticRecall=false when no backend is wired', () => {
-        const r = index_1.SemanticRetriever.create({ index: buildIndex([]) }).orThrow();
-        expect(r.capabilities.supportsSemanticRecall).toBe(false);
-    });
-    test('reports supportsSemanticRecall=true when a backend is wired', () => {
-        const r = index_1.SemanticRetriever.create({
-            index: buildIndex([]),
-            backend: { vectorIndex: new FakeVectorIndex([]), embedQuery: okEmbed }
-        }).orThrow();
-        expect(r.capabilities.supportsSemanticRecall).toBe(true);
-    });
-    test('degrades loudly on a semantic request when no backend is wired', async () => {
-        const r = index_1.SemanticRetriever.create({ index: buildIndex([{ id: 'a' }]) }).orThrow();
-        expect(await r.retrieve({ semantic: 'hi' })).toFailWith(/semantic recall requires a vector index; none configured/i);
-    });
-    test('returns empty (not failure) when no semantic term is supplied', async () => {
-        const r = index_1.SemanticRetriever.create({ index: buildIndex([{ id: 'a' }]) }).orThrow();
-        expect(await r.retrieve({})).toSucceedWith([]);
-    });
-    test('degrades loudly on an as-of request', async () => {
-        const r = index_1.SemanticRetriever.create({ index: buildIndex([{ id: 'a' }]) }).orThrow();
-        expect(await r.retrieve({ asOf: 5 })).toFailWith(/temporal query requires temporal index/i);
-    });
-    test('resolves vector hits back to records in hit order', async () => {
-        const index = buildIndex([
-            { id: 'a', updated: 1 },
-            { id: 'b', updated: 99 },
-            { id: 'c', updated: 50 }
-        ]);
-        const r = index_1.SemanticRetriever.create({
-            index,
-            backend: {
-                vectorIndex: new FakeVectorIndex([
-                    { target: et('b'), score: 0.9 },
-                    { target: et('a'), score: 0.5 }
-                ]),
-                embedQuery: okEmbed
-            }
-        }).orThrow();
-        expect(await r.retrieve({ semantic: 'q' })).toSucceedAndSatisfy((records) => {
-            // Hit order preserved (b before a), NOT recency order.
-            expect(ids(records)).toEqual(['b', 'a']);
-        });
-    });
-    test('drops hits not present in the index and applies query filters', async () => {
-        const index = buildIndex([
-            { id: 'a', tags: ['x'] },
-            { id: 'b', tags: ['y'] }
-        ]);
-        const r = index_1.SemanticRetriever.create({
-            index,
-            backend: {
-                vectorIndex: new FakeVectorIndex([
-                    { target: et('gone'), score: 0.99 },
-                    { target: et('b'), score: 0.8 },
-                    { target: et('a'), score: 0.7 }
-                ]),
-                embedQuery: okEmbed
-            }
-        }).orThrow();
-        expect(await r.retrieve({ semantic: 'q', tag: 'x' })).toSucceedAndSatisfy((records) => {
-            expect(ids(records)).toEqual(['a']);
-        });
-    });
-    test('resolves a hit to the correctly-scoped record when two records share an id stem across scopes', async () => {
-        // Two records with the identical stem `turn-3` under different scopes — the
-        // exact same-stem-across-scopes collision the scope-qualified hit fixes. The
-        // retriever must re-resolve each hit through its full `(scope, id)` key, not a
-        // bare id (which would ambiguously match either record).
-        const index = buildIndex([
-            { id: 'turn-3', scope: 'conv-a', tags: ['from-a'] },
-            { id: 'turn-3', scope: 'conv-b', tags: ['from-b'] }
-        ]);
-        const r = index_1.SemanticRetriever.create({
-            index,
-            backend: {
-                // The vector backend scored the conv-b record; the retriever must return
-                // exactly that record, never the same-stem conv-a record.
-                vectorIndex: new FakeVectorIndex([{ target: et('turn-3', 'conv-b'), score: 0.9 }]),
-                embedQuery: okEmbed
-            }
-        }).orThrow();
-        expect(await r.retrieve({ semantic: 'q' })).toSucceedAndSatisfy((records) => {
-            expect(records).toHaveLength(1);
-            expect(records[0].envelope.id).toBe('turn-3');
-            // The tag proves it is the conv-b record, not the same-stem conv-a one.
-            expect(records[0].envelope.tags).toEqual(['from-b']);
-        });
-    });
-    test('forwards topK to the vector index and applies the post-filter limit', async () => {
-        const index = buildIndex([{ id: 'a' }, { id: 'b' }, { id: 'c' }]);
-        const vectorIndex = new FakeVectorIndex([
-            { target: et('a'), score: 0.9 },
-            { target: et('b'), score: 0.8 },
-            { target: et('c'), score: 0.7 }
-        ]);
-        const r = index_1.SemanticRetriever.create({ index, backend: { vectorIndex, embedQuery: okEmbed } }).orThrow();
-        expect(await r.retrieve({ semantic: 'q', topK: 2, limit: 2 })).toSucceedAndSatisfy((records) => {
-            expect(ids(records)).toEqual(['a', 'b']);
-        });
-        // The retriever must forward the caller's topK to the vector backend, not its default.
-        expect(vectorIndex.lastTopK).toBe(2);
-    });
-    test('defaults topK to 10 when the query omits it', async () => {
-        const vectorIndex = new FakeVectorIndex([{ target: et('a'), score: 0.9 }]);
-        const r = index_1.SemanticRetriever.create({
-            index: buildIndex([{ id: 'a' }]),
-            backend: { vectorIndex, embedQuery: okEmbed }
-        }).orThrow();
-        expect(await r.retrieve({ semantic: 'q' })).toSucceed();
-        expect(vectorIndex.lastTopK).toBe(10);
-    });
-    test('fails loudly when the embedder fails', async () => {
-        const r = index_1.SemanticRetriever.create({
-            index: buildIndex([{ id: 'a' }]),
-            backend: {
-                vectorIndex: new FakeVectorIndex([]),
-                embedQuery: () => Promise.resolve((0, ts_utils_1.fail)('no embed model'))
-            }
-        }).orThrow();
-        expect(await r.retrieve({ semantic: 'q' })).toFailWith(/query embedding failed: no embed model/i);
-    });
-    test('fails loudly when the vector backend fails', async () => {
-        const r = index_1.SemanticRetriever.create({
-            index: buildIndex([{ id: 'a' }]),
-            backend: { vectorIndex: new FakeVectorIndex([], true), embedQuery: okEmbed }
-        }).orThrow();
-        expect(await r.retrieve({ semantic: 'q' })).toFailWith(/vector query failed: vector backend down/i);
-    });
-    test('normalizes a rejecting embedder into a Failure (never escapes as a rejection)', async () => {
-        const r = index_1.SemanticRetriever.create({
-            index: buildIndex([{ id: 'a' }]),
-            backend: {
-                vectorIndex: new FakeVectorIndex([]),
-                embedQuery: () => Promise.reject(new Error('embedder blew up'))
-            }
-        }).orThrow();
-        expect(await r.retrieve({ semantic: 'q' })).toFailWith(/query embedding failed: .*embedder blew up/i);
-    });
-    test('normalizes a rejecting vector backend into a Failure', async () => {
-        // A vector index whose `query` rejects (throws) rather than returning a fail.
-        const rejectingIndex = {
-            add: (t) => Promise.resolve((0, ts_utils_1.succeed)(`ref-${t.id}`)),
-            remove: (t) => Promise.resolve((0, ts_utils_1.succeed)(t)),
-            query: () => Promise.reject(new Error('socket hangup'))
-        };
-        const r = index_1.SemanticRetriever.create({
-            index: buildIndex([{ id: 'a' }]),
-            backend: { vectorIndex: rejectingIndex, embedQuery: okEmbed }
-        }).orThrow();
-        expect(await r.retrieve({ semantic: 'q' })).toFailWith(/vector query failed: .*socket hangup/i);
-    });
-});
-describe('ScoreUnionMergeStrategy', () => {
-    test('unions, dedupes by id, and scores by retriever count', () => {
-        const strategy = index_1.ScoreUnionMergeStrategy.create().orThrow();
-        const [a, b, c] = [
-            makeEntry({ id: 'a', updated: 10 }).record,
-            makeEntry({ id: 'b', updated: 30 }).record,
-            makeEntry({ id: 'c', updated: 20 }).record
-        ];
-        // 'b' appears in two sets (score 2); 'a' and 'c' in one each (score 1) — among
-        // score-1 records, recency breaks the tie (c.updated 20 > a.updated 10).
-        expect(strategy.merge([
-            [a, b],
-            [b, c]
-        ])).toSucceedAndSatisfy((records) => {
-            expect(ids(records)).toEqual(['b', 'c', 'a']);
-        });
-    });
-    test('counts an id at most once per result set', () => {
-        const strategy = index_1.ScoreUnionMergeStrategy.create().orThrow();
-        const a = makeEntry({ id: 'a', updated: 10 }).record;
-        const b = makeEntry({ id: 'b', updated: 5 }).record;
-        // 'a' twice in one set still scores 1; 'b' in two sets scores 2 → b ranks first.
-        expect(strategy.merge([[a, a], [b], [b]])).toSucceedAndSatisfy((records) => {
-            expect(ids(records)).toEqual(['b', 'a']);
-        });
-    });
-});
-describe('HybridRetriever', () => {
-    function build() {
-        return {
-            index: buildIndex([
-                { id: 'a', tags: ['x'], updated: 10 },
-                { id: 'b', tags: ['y'], updated: 30 },
-                { id: 'c', tags: ['x'], updated: 20 }
-            ])
-        };
-    }
-    test('requires at least one retriever', () => {
-        const strategy = index_1.ScoreUnionMergeStrategy.create().orThrow();
-        expect(index_1.HybridRetriever.create([], strategy)).toFailWith(/at least one retriever is required/i);
-    });
-    test('capabilities are the union of composed retrievers', () => {
-        const { index } = build();
-        const recency = index_1.RecencyRetriever.create(index).orThrow();
-        const semantic = index_1.SemanticRetriever.create({
-            index,
-            backend: {
-                vectorIndex: new FakeVectorIndex([]),
-                embedQuery: () => Promise.resolve((0, ts_utils_1.succeed)(Float32Array.from([1])))
-            }
-        }).orThrow();
-        const hybrid = index_1.HybridRetriever.create([recency, semantic], index_1.ScoreUnionMergeStrategy.create().orThrow()).orThrow();
-        expect(hybrid.capabilities).toEqual({
-            supportsSemanticRecall: true,
-            supportsTemporalQuery: false,
-            supportsLinkTraversal: false
-        });
-    });
-    test('merges the results of composed retrievers', async () => {
-        const { index } = build();
-        const recency = index_1.RecencyRetriever.create(index).orThrow();
-        const tag = index_1.TagRetriever.create(index).orThrow();
-        const hybrid = index_1.HybridRetriever.create([recency, tag], index_1.ScoreUnionMergeStrategy.create().orThrow()).orThrow();
-        // recency returns a,b,c (with tag x filter: a,c); tag x returns a,c. Both
-        // surface a & c (score 2), b absent. Use tag:x so recency also filters to x.
-        expect(await hybrid.retrieve({ tag: 'x' })).toSucceedAndSatisfy((records) => {
-            expect([...ids(records)].sort()).toEqual(['a', 'c']);
-        });
-    });
-    test('routes a semantic query only to the semantic-capable child', async () => {
-        const { index } = build();
-        const recency = index_1.RecencyRetriever.create(index).orThrow();
-        const semantic = index_1.SemanticRetriever.create({
-            index,
-            backend: {
-                vectorIndex: new FakeVectorIndex([{ target: et('b'), score: 0.9 }]),
-                embedQuery: () => Promise.resolve((0, ts_utils_1.succeed)(Float32Array.from([1])))
-            }
-        }).orThrow();
-        const hybrid = index_1.HybridRetriever.create([recency, semantic], index_1.ScoreUnionMergeStrategy.create().orThrow()).orThrow();
-        // recency (no semantic support) gets the semantic field stripped → returns all
-        // three; semantic returns just b. b therefore scores 2 and ranks first.
-        expect(await hybrid.retrieve({ semantic: 'q' })).toSucceedAndSatisfy((records) => {
-            expect(records[0].envelope.id).toBe('b');
-            expect([...ids(records)].sort()).toEqual(['a', 'b', 'c']);
-        });
-    });
-    test('routes link-traversal axes only to the link-capable child', async () => {
-        var _a, _b, _c, _d;
-        const linkChild = new RecordingRetriever({
-            supportsSemanticRecall: false,
-            supportsTemporalQuery: false,
-            supportsLinkTraversal: true
-        });
-        const plainChild = new RecordingRetriever({
-            supportsSemanticRecall: false,
-            supportsTemporalQuery: false,
-            supportsLinkTraversal: false
-        });
-        const hybrid = index_1.HybridRetriever.create([linkChild, plainChild], index_1.ScoreUnionMergeStrategy.create().orThrow()).orThrow();
-        expect(hybrid.capabilities.supportsLinkTraversal).toBe(true);
-        // Union supports link traversal, so the hybrid does NOT loud-fail.
-        expect(await hybrid.retrieve({ linkedTo: et('a'), hops: 2 })).toSucceed();
-        // The link-capable child keeps the axes; the plain child has them stripped.
-        expect((_a = linkChild.lastQuery) === null || _a === void 0 ? void 0 : _a.linkedTo).toEqual(et('a'));
-        expect((_b = linkChild.lastQuery) === null || _b === void 0 ? void 0 : _b.hops).toBe(2);
-        expect((_c = plainChild.lastQuery) === null || _c === void 0 ? void 0 : _c.linkedTo).toBeUndefined();
-        expect((_d = plainChild.lastQuery) === null || _d === void 0 ? void 0 : _d.hops).toBeUndefined();
-    });
-    test('degrades loudly when its union does not support a requested capability', async () => {
-        const { index } = build();
-        const recency = index_1.RecencyRetriever.create(index).orThrow();
-        const hybrid = index_1.HybridRetriever.create([recency], index_1.ScoreUnionMergeStrategy.create().orThrow()).orThrow();
-        expect(await hybrid.retrieve({ semantic: 'q' })).toFailWith(/semantic recall requires/i);
-    });
-    test('propagates a child failure rather than dropping it silently', async () => {
-        const { index } = build();
-        const semantic = index_1.SemanticRetriever.create({
-            index,
-            backend: {
-                vectorIndex: new FakeVectorIndex([], true),
-                embedQuery: () => Promise.resolve((0, ts_utils_1.succeed)(Float32Array.from([1])))
-            }
-        }).orThrow();
-        const hybrid = index_1.HybridRetriever.create([semantic], index_1.ScoreUnionMergeStrategy.create().orThrow()).orThrow();
-        expect(await hybrid.retrieve({ semantic: 'q' })).toFailWith(/vector query failed/i);
-    });
-    test('does not pre-truncate child result sets: limit is applied only post-merge', async () => {
-        // Recency full order is [d,c,b,a]; semantic surfaces [d,a]. With a correct
-        // (post-merge-only) limit, the merge sees BOTH full sets, so d and a each
-        // score 2 and the limit-2 result is [d,a]. If the limit leaked into the
-        // children, recency would pre-truncate to [d,c] and the result would wrongly
-        // be [d,c] — a never reaching the merge to score 2.
-        const index = buildIndex([
-            { id: 'a', updated: 10 },
-            { id: 'b', updated: 20 },
-            { id: 'c', updated: 30 },
-            { id: 'd', updated: 40 }
-        ]);
-        const recency = index_1.RecencyRetriever.create(index).orThrow();
-        const semantic = index_1.SemanticRetriever.create({
-            index,
-            backend: {
-                vectorIndex: new FakeVectorIndex([
-                    { target: et('d'), score: 0.9 },
-                    { target: et('a'), score: 0.8 }
-                ]),
-                embedQuery: () => Promise.resolve((0, ts_utils_1.succeed)(Float32Array.from([1])))
-            }
-        }).orThrow();
-        const hybrid = index_1.HybridRetriever.create([recency, semantic], index_1.ScoreUnionMergeStrategy.create().orThrow()).orThrow();
-        expect(await hybrid.retrieve({ semantic: 'q', limit: 2 })).toSucceedAndSatisfy((records) => {
-            expect(ids(records)).toEqual(['d', 'a']);
-        });
-    });
-    test('applies the hybrid-level limit after merge', async () => {
-        const { index } = build();
-        const recency = index_1.RecencyRetriever.create(index).orThrow();
-        const hybrid = index_1.HybridRetriever.create([recency], index_1.ScoreUnionMergeStrategy.create().orThrow()).orThrow();
-        expect(await hybrid.retrieve({ limit: 1 })).toSucceedAndSatisfy((records) => {
-            expect(records).toHaveLength(1);
-            expect(records[0].envelope.id).toBe('b');
-        });
-    });
-    test('applies the { offset, limit } window after merge', async () => {
-        const { index } = build();
-        const recency = index_1.RecencyRetriever.create(index).orThrow();
-        const hybrid = index_1.HybridRetriever.create([recency], index_1.ScoreUnionMergeStrategy.create().orThrow()).orThrow();
-        // Merged recency order is [b(30), c(20), a(10)]; offset 1 + limit 1 → [c].
-        expect(await hybrid.retrieve({ offset: 1, limit: 1 })).toSucceedAndSatisfy((records) => {
-            expect(ids(records)).toEqual(['c']);
-        });
-    });
-    test('strips offset from child queries (offset is a post-merge concern)', async () => {
-        var _a, _b;
-        const child = new RecordingRetriever({
-            supportsSemanticRecall: false,
-            supportsTemporalQuery: false,
-            supportsLinkTraversal: false
-        });
-        const hybrid = index_1.HybridRetriever.create([child], index_1.ScoreUnionMergeStrategy.create().orThrow()).orThrow();
-        expect(await hybrid.retrieve({ offset: 2, limit: 3 })).toSucceed();
-        expect((_a = child.lastQuery) === null || _a === void 0 ? void 0 : _a.offset).toBeUndefined();
-        expect((_b = child.lastQuery) === null || _b === void 0 ? void 0 : _b.limit).toBeUndefined();
-    });
-    test('passes the kinds axis through to children (a shared pre-filter axis)', async () => {
-        var _a;
-        const child = new RecordingRetriever({
-            supportsSemanticRecall: false,
-            supportsTemporalQuery: false,
-            supportsLinkTraversal: false
-        });
-        const hybrid = index_1.HybridRetriever.create([child], index_1.ScoreUnionMergeStrategy.create().orThrow()).orThrow();
-        expect(await hybrid.retrieve({ kinds: ['knowledge'] })).toSucceed();
-        expect((_a = child.lastQuery) === null || _a === void 0 ? void 0 : _a.kinds).toEqual(['knowledge']);
-    });
-});
-//# sourceMappingURL=retrievers.test.js.map