@fgv/ts-agent-memory 5.1.0-36

package/dist/test/unit/retrieve/linkTraversalRetriever.test.js

@@ -0,0 +1,182 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+import '@fgv/ts-utils-jest';
+import { LinkTraversalRetriever, LINK_TRAVERSAL_NO_SEED_MESSAGE, LINK_TRAVERSAL_UNWIRED_MESSAGE, MemoryIndex, envelopeConverter } from '../../../index';
+function makeEntry(spec) {
+    var _a, _b, _c, _d, _e, _f;
+    const record = {
+        envelope: envelopeConverter
+            .convert({
+            id: spec.id,
+            entityId: spec.id,
+            kind: (_a = spec.kind) !== null && _a !== void 0 ? _a : 'experience',
+            tags: (_b = spec.tags) !== null && _b !== void 0 ? _b : [],
+            links: ((_c = spec.links) !== null && _c !== void 0 ? _c : []).map((target) => ({ type: 'rel', target })),
+            created: 0,
+            updated: (_d = spec.updated) !== null && _d !== void 0 ? _d : 0,
+            seq: (_e = spec.seq) !== null && _e !== void 0 ? _e : 0,
+            contentHash: 'h',
+            provenance: { source: 'agent' }
+        })
+            .orThrow(),
+        body: `body-${spec.id}`
+    };
+    return { scope: ((_f = spec.scope) !== null && _f !== void 0 ? _f : 'experience'), record };
+}
+function buildIndex(specs) {
+    const index = MemoryIndex.create().orThrow();
+    index.rebuild(specs.map(makeEntry)).orThrow();
+    return index;
+}
+function ids(records) {
+    return records.map((r) => r.envelope.id);
+}
+describe('LinkTraversalRetriever', () => {
+    test('reports the link-traversal capability', () => {
+        const index = buildIndex([]);
+        const retriever = LinkTraversalRetriever.create(index).orThrow();
+        expect(retriever.capabilities).toEqual({
+            supportsSemanticRecall: false,
+            supportsTemporalQuery: false,
+            supportsLinkTraversal: true
+        });
+    });
+    describe('outbound traversal (linkedFrom)', () => {
+        test('returns the direct outbound neighbors at the default single hop', async () => {
+            const index = buildIndex([
+                { id: 'a', links: ['b', 'c'] },
+                { id: 'b', updated: 20 },
+                { id: 'c', updated: 10 }
+            ]);
+            const retriever = LinkTraversalRetriever.create(index).orThrow();
+            expect(await retriever.retrieve({ linkedFrom: 'a' })).toSucceedAndSatisfy((records) => {
+                // Recency-ordered: b (updated 20) before c (updated 10). 'a' (the seed) excluded.
+                expect(ids(records)).toEqual(['b', 'c']);
+            });
+        });
+        test('stops at the default single hop (does not reach 2-hop neighbors)', async () => {
+            const index = buildIndex([{ id: 'a', links: ['b'] }, { id: 'b', links: ['c'] }, { id: 'c' }]);
+            const retriever = LinkTraversalRetriever.create(index).orThrow();
+            expect(await retriever.retrieve({ linkedFrom: 'a' })).toSucceedAndSatisfy((records) => {
+                expect(ids(records)).toEqual(['b']);
+            });
+        });
+        test('follows multiple hops when hops is raised', async () => {
+            const index = buildIndex([{ id: 'a', links: ['b'] }, { id: 'b', links: ['c'] }, { id: 'c' }]);
+            const retriever = LinkTraversalRetriever.create(index).orThrow();
+            expect(await retriever.retrieve({ linkedFrom: 'a', hops: 2 })).toSucceedAndSatisfy((records) => {
+                expect(ids(records).sort()).toEqual(['b', 'c']);
+            });
+        });
+    });
+    describe('inbound traversal (linkedTo)', () => {
+        test('returns the records whose edges point at the seed (backlinks)', async () => {
+            const index = buildIndex([
+                { id: 'a', links: ['target'], updated: 30 },
+                { id: 'b', links: ['target'], updated: 10 },
+                { id: 'target' }
+            ]);
+            const retriever = LinkTraversalRetriever.create(index).orThrow();
+            expect(await retriever.retrieve({ linkedTo: 'target' })).toSucceedAndSatisfy((records) => {
+                expect(ids(records)).toEqual(['a', 'b']);
+            });
+        });
+    });
+    describe('cycle safety', () => {
+        test('terminates on a self-loop and excludes the seed', async () => {
+            const index = buildIndex([{ id: 'a', links: ['a'] }]);
+            const retriever = LinkTraversalRetriever.create(index).orThrow();
+            expect(await retriever.retrieve({ linkedFrom: 'a', hops: 5 })).toSucceedAndSatisfy((records) => {
+                expect(records).toHaveLength(0);
+            });
+        });
+        test('terminates on a multi-hop cycle without revisiting', async () => {
+            const index = buildIndex([
+                { id: 'a', links: ['b'] },
+                { id: 'b', links: ['c'] },
+                { id: 'c', links: ['a'] }
+            ]);
+            const retriever = LinkTraversalRetriever.create(index).orThrow();
+            expect(await retriever.retrieve({ linkedFrom: 'a', hops: 10 })).toSucceedAndSatisfy((records) => {
+                // a→b→c→a: reaches b and c, then the edge back to the seed is pruned.
+                expect(ids(records).sort()).toEqual(['b', 'c']);
+            });
+        });
+    });
+    test('traverses a cross-kind edge (experience derivedFrom a knowledge doc)', async () => {
+        const index = buildIndex([
+            { id: 'turn-5', scope: 'conversations/conv-1', kind: 'summarized-turn', links: ['doc-1'] },
+            { id: 'doc-1', scope: 'knowledge', kind: 'knowledge' }
+        ]);
+        const retriever = LinkTraversalRetriever.create(index).orThrow();
+        expect(await retriever.retrieve({ linkedFrom: 'turn-5' })).toSucceedAndSatisfy((records) => {
+            expect(ids(records)).toEqual(['doc-1']);
+            expect(records[0].envelope.kind).toBe('knowledge');
+        });
+    });
+    describe('post-filtering and bounds', () => {
+        test('applies the kind pre-filter to the reached records', async () => {
+            const index = buildIndex([
+                { id: 'a', links: ['b', 'c'] },
+                { id: 'b', kind: 'keep' },
+                { id: 'c', kind: 'drop' }
+            ]);
+            const retriever = LinkTraversalRetriever.create(index).orThrow();
+            expect(await retriever.retrieve({ linkedFrom: 'a', kind: 'keep' })).toSucceedAndSatisfy((records) => {
+                expect(ids(records)).toEqual(['b']);
+            });
+        });
+        test('applies the limit after ordering', async () => {
+            const index = buildIndex([
+                { id: 'a', links: ['b', 'c', 'd'] },
+                { id: 'b', updated: 30 },
+                { id: 'c', updated: 20 },
+                { id: 'd', updated: 10 }
+            ]);
+            const retriever = LinkTraversalRetriever.create(index).orThrow();
+            expect(await retriever.retrieve({ linkedFrom: 'a', limit: 2 })).toSucceedAndSatisfy((records) => {
+                expect(ids(records)).toEqual(['b', 'c']);
+            });
+        });
+        test('returns empty when the seed is not in the index', async () => {
+            const index = buildIndex([{ id: 'a', links: ['b'] }, { id: 'b' }]);
+            const retriever = LinkTraversalRetriever.create(index).orThrow();
+            expect(await retriever.retrieve({ linkedFrom: 'missing' })).toSucceedWith([]);
+        });
+        test('resolves every record sharing a reached id (cross-scope id reuse)', async () => {
+            const index = buildIndex([
+                { id: 'seed', scope: 'a', links: ['dup'] },
+                { id: 'dup', scope: 'a' },
+                { id: 'dup', scope: 'b' }
+            ]);
+            const retriever = LinkTraversalRetriever.create(index).orThrow();
+            expect(await retriever.retrieve({ linkedFrom: 'seed' })).toSucceedAndSatisfy((records) => {
+                expect(records).toHaveLength(2);
+                expect(ids(records)).toEqual(['dup', 'dup']);
+            });
+        });
+    });
+    describe('loud degradation', () => {
+        test('fails when no seed (linkedFrom / linkedTo) is supplied', async () => {
+            const index = buildIndex([{ id: 'a' }]);
+            const retriever = LinkTraversalRetriever.create(index).orThrow();
+            expect(await retriever.retrieve({ hops: 2 })).toFailWith(LINK_TRAVERSAL_NO_SEED_MESSAGE);
+        });
+    });
+});
+describe('LINK_TRAVERSAL_UNWIRED_MESSAGE constant', () => {
+    test('has the stable public message non-link retrievers use to degrade loudly', () => {
+        // The link-traversal retriever supports the axis, so it never emits this
+        // message; the constant is the shared one the non-link v1 retrievers raise
+        // (asserted here to keep the public string stable).
+        expect(LINK_TRAVERSAL_UNWIRED_MESSAGE).toMatch(/link traversal requires a backlink index/i);
+    });
+    test('a link query against the link-capable retriever still succeeds', async () => {
+        const index = buildIndex([{ id: 'a', links: ['b'] }, { id: 'b' }]);
+        const retriever = LinkTraversalRetriever.create(index).orThrow();
+        expect(await retriever.retrieve({ linkedFrom: 'a' })).toSucceed();
+    });
+});
+//# sourceMappingURL=linkTraversalRetriever.test.js.map

package/dist/test/unit/retrieve/linkTraversalRetriever.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"linkTraversalRetriever.test.js","sourceRoot":"","sources":["../../../../src/test/unit/retrieve/linkTraversalRetriever.test.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport '@fgv/ts-utils-jest';\nimport {\n  IIndexedMemoryRecord,\n  IMemoryRecord,\n  Kind,\n  LinkTraversalRetriever,\n  LINK_TRAVERSAL_NO_SEED_MESSAGE,\n  LINK_TRAVERSAL_UNWIRED_MESSAGE,\n  MemoryId,\n  MemoryIndex,\n  MemoryScopeKey,\n  envelopeConverter\n} from '../../../index';\n\ninterface IEntrySpec {\n  readonly id: string;\n  readonly scope?: string;\n  readonly kind?: string;\n  readonly tags?: ReadonlyArray<string>;\n  readonly updated?: number;\n  readonly seq?: number;\n  readonly links?: ReadonlyArray<string>;\n}\n\nfunction makeEntry(spec: IEntrySpec): IIndexedMemoryRecord {\n  const record: IMemoryRecord<unknown> = {\n    envelope: envelopeConverter\n      .convert({\n        id: spec.id,\n        entityId: spec.id,\n        kind: spec.kind ?? 'experience',\n        tags: spec.tags ?? [],\n        links: (spec.links ?? []).map((target) => ({ type: 'rel', target })),\n        created: 0,\n        updated: spec.updated ?? 0,\n        seq: spec.seq ?? 0,\n        contentHash: 'h',\n        provenance: { source: 'agent' }\n      })\n      .orThrow(),\n    body: `body-${spec.id}`\n  };\n  return { scope: (spec.scope ?? 'experience') as MemoryScopeKey, record };\n}\n\nfunction buildIndex(specs: ReadonlyArray<IEntrySpec>): MemoryIndex {\n  const index = MemoryIndex.create().orThrow();\n  index.rebuild(specs.map(makeEntry)).orThrow();\n  return index;\n}\n\nfunction ids(records: ReadonlyArray<IMemoryRecord<unknown>>): string[] {\n  return records.map((r) => r.envelope.id as string);\n}\n\ndescribe('LinkTraversalRetriever', () => {\n  test('reports the link-traversal capability', () => {\n    const index = buildIndex([]);\n    const retriever = LinkTraversalRetriever.create(index).orThrow();\n    expect(retriever.capabilities).toEqual({\n      supportsSemanticRecall: false,\n      supportsTemporalQuery: false,\n      supportsLinkTraversal: true\n    });\n  });\n\n  describe('outbound traversal (linkedFrom)', () => {\n    test('returns the direct outbound neighbors at the default single hop', async () => {\n      const index = buildIndex([\n        { id: 'a', links: ['b', 'c'] },\n        { id: 'b', updated: 20 },\n        { id: 'c', updated: 10 }\n      ]);\n      const retriever = LinkTraversalRetriever.create(index).orThrow();\n      expect(await retriever.retrieve({ linkedFrom: 'a' as MemoryId })).toSucceedAndSatisfy((records) => {\n        // Recency-ordered: b (updated 20) before c (updated 10). 'a' (the seed) excluded.\n        expect(ids(records)).toEqual(['b', 'c']);\n      });\n    });\n\n    test('stops at the default single hop (does not reach 2-hop neighbors)', async () => {\n      const index = buildIndex([{ id: 'a', links: ['b'] }, { id: 'b', links: ['c'] }, { id: 'c' }]);\n      const retriever = LinkTraversalRetriever.create(index).orThrow();\n      expect(await retriever.retrieve({ linkedFrom: 'a' as MemoryId })).toSucceedAndSatisfy((records) => {\n        expect(ids(records)).toEqual(['b']);\n      });\n    });\n\n    test('follows multiple hops when hops is raised', async () => {\n      const index = buildIndex([{ id: 'a', links: ['b'] }, { id: 'b', links: ['c'] }, { id: 'c' }]);\n      const retriever = LinkTraversalRetriever.create(index).orThrow();\n      expect(await retriever.retrieve({ linkedFrom: 'a' as MemoryId, hops: 2 })).toSucceedAndSatisfy(\n        (records) => {\n          expect(ids(records).sort()).toEqual(['b', 'c']);\n        }\n      );\n    });\n  });\n\n  describe('inbound traversal (linkedTo)', () => {\n    test('returns the records whose edges point at the seed (backlinks)', async () => {\n      const index = buildIndex([\n        { id: 'a', links: ['target'], updated: 30 },\n        { id: 'b', links: ['target'], updated: 10 },\n        { id: 'target' }\n      ]);\n      const retriever = LinkTraversalRetriever.create(index).orThrow();\n      expect(await retriever.retrieve({ linkedTo: 'target' as MemoryId })).toSucceedAndSatisfy((records) => {\n        expect(ids(records)).toEqual(['a', 'b']);\n      });\n    });\n  });\n\n  describe('cycle safety', () => {\n    test('terminates on a self-loop and excludes the seed', async () => {\n      const index = buildIndex([{ id: 'a', links: ['a'] }]);\n      const retriever = LinkTraversalRetriever.create(index).orThrow();\n      expect(await retriever.retrieve({ linkedFrom: 'a' as MemoryId, hops: 5 })).toSucceedAndSatisfy(\n        (records) => {\n          expect(records).toHaveLength(0);\n        }\n      );\n    });\n\n    test('terminates on a multi-hop cycle without revisiting', async () => {\n      const index = buildIndex([\n        { id: 'a', links: ['b'] },\n        { id: 'b', links: ['c'] },\n        { id: 'c', links: ['a'] }\n      ]);\n      const retriever = LinkTraversalRetriever.create(index).orThrow();\n      expect(await retriever.retrieve({ linkedFrom: 'a' as MemoryId, hops: 10 })).toSucceedAndSatisfy(\n        (records) => {\n          // a→b→c→a: reaches b and c, then the edge back to the seed is pruned.\n          expect(ids(records).sort()).toEqual(['b', 'c']);\n        }\n      );\n    });\n  });\n\n  test('traverses a cross-kind edge (experience derivedFrom a knowledge doc)', async () => {\n    const index = buildIndex([\n      { id: 'turn-5', scope: 'conversations/conv-1', kind: 'summarized-turn', links: ['doc-1'] },\n      { id: 'doc-1', scope: 'knowledge', kind: 'knowledge' }\n    ]);\n    const retriever = LinkTraversalRetriever.create(index).orThrow();\n    expect(await retriever.retrieve({ linkedFrom: 'turn-5' as MemoryId })).toSucceedAndSatisfy((records) => {\n      expect(ids(records)).toEqual(['doc-1']);\n      expect(records[0].envelope.kind).toBe('knowledge');\n    });\n  });\n\n  describe('post-filtering and bounds', () => {\n    test('applies the kind pre-filter to the reached records', async () => {\n      const index = buildIndex([\n        { id: 'a', links: ['b', 'c'] },\n        { id: 'b', kind: 'keep' },\n        { id: 'c', kind: 'drop' }\n      ]);\n      const retriever = LinkTraversalRetriever.create(index).orThrow();\n      expect(\n        await retriever.retrieve({ linkedFrom: 'a' as MemoryId, kind: 'keep' as unknown as Kind })\n      ).toSucceedAndSatisfy((records) => {\n        expect(ids(records)).toEqual(['b']);\n      });\n    });\n\n    test('applies the limit after ordering', async () => {\n      const index = buildIndex([\n        { id: 'a', links: ['b', 'c', 'd'] },\n        { id: 'b', updated: 30 },\n        { id: 'c', updated: 20 },\n        { id: 'd', updated: 10 }\n      ]);\n      const retriever = LinkTraversalRetriever.create(index).orThrow();\n      expect(await retriever.retrieve({ linkedFrom: 'a' as MemoryId, limit: 2 })).toSucceedAndSatisfy(\n        (records) => {\n          expect(ids(records)).toEqual(['b', 'c']);\n        }\n      );\n    });\n\n    test('returns empty when the seed is not in the index', async () => {\n      const index = buildIndex([{ id: 'a', links: ['b'] }, { id: 'b' }]);\n      const retriever = LinkTraversalRetriever.create(index).orThrow();\n      expect(await retriever.retrieve({ linkedFrom: 'missing' as MemoryId })).toSucceedWith([]);\n    });\n\n    test('resolves every record sharing a reached id (cross-scope id reuse)', async () => {\n      const index = buildIndex([\n        { id: 'seed', scope: 'a', links: ['dup'] },\n        { id: 'dup', scope: 'a' },\n        { id: 'dup', scope: 'b' }\n      ]);\n      const retriever = LinkTraversalRetriever.create(index).orThrow();\n      expect(await retriever.retrieve({ linkedFrom: 'seed' as MemoryId })).toSucceedAndSatisfy((records) => {\n        expect(records).toHaveLength(2);\n        expect(ids(records)).toEqual(['dup', 'dup']);\n      });\n    });\n  });\n\n  describe('loud degradation', () => {\n    test('fails when no seed (linkedFrom / linkedTo) is supplied', async () => {\n      const index = buildIndex([{ id: 'a' }]);\n      const retriever = LinkTraversalRetriever.create(index).orThrow();\n      expect(await retriever.retrieve({ hops: 2 })).toFailWith(LINK_TRAVERSAL_NO_SEED_MESSAGE);\n    });\n  });\n});\n\ndescribe('LINK_TRAVERSAL_UNWIRED_MESSAGE constant', () => {\n  test('has the stable public message non-link retrievers use to degrade loudly', () => {\n    // The link-traversal retriever supports the axis, so it never emits this\n    // message; the constant is the shared one the non-link v1 retrievers raise\n    // (asserted here to keep the public string stable).\n    expect(LINK_TRAVERSAL_UNWIRED_MESSAGE).toMatch(/link traversal requires a backlink index/i);\n  });\n\n  test('a link query against the link-capable retriever still succeeds', async () => {\n    const index = buildIndex([{ id: 'a', links: ['b'] }, { id: 'b' }]);\n    const retriever = LinkTraversalRetriever.create(index).orThrow();\n    expect(await retriever.retrieve({ linkedFrom: 'a' as MemoryId })).toSucceed();\n  });\n});\n"]}