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

package/src/test/unit/observe/memoryObservationStore.test.ts

@@ -1,158 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import '@fgv/ts-utils-jest';
-import {
-  IMemoryObservationRecord,
-  Kind,
-  MemoryId,
-  MemoryObservationPhase,
-  MemoryObservationStore,
-  MemoryScopeKey
-} from '../../../index';
-
-interface IObsSpec {
-  readonly seq: number;
-  readonly timestamp?: number;
-  readonly phase?: MemoryObservationPhase;
-  readonly scope?: string;
-  readonly kind?: string;
-  readonly id?: string;
-  readonly outcome?: 'success' | 'failure';
-}
-
-function obs(spec: IObsSpec): IMemoryObservationRecord {
-  return {
-    seq: spec.seq,
-    timestamp: spec.timestamp ?? spec.seq,
-    phase: spec.phase ?? 'write',
-    scope: spec.scope === undefined ? undefined : (spec.scope as MemoryScopeKey),
-    kind: spec.kind === undefined ? undefined : (spec.kind as Kind),
-    id: spec.id === undefined ? undefined : (spec.id as MemoryId),
-    outcome: spec.outcome ?? 'success'
-  };
-}
-
-function seqs(records: ReadonlyArray<IMemoryObservationRecord>): ReadonlyArray<number> {
-  return records.map((r) => r.seq);
-}
-
-describe('MemoryObservationStore', () => {
-  describe('create', () => {
-    test('builds with defaults', () => {
-      expect(MemoryObservationStore.create()).toSucceedAndSatisfy((store: MemoryObservationStore) => {
-        expect(store.size).toBe(0);
-        expect(store.lastSeq).toBe(0);
-      });
-    });
-
-    test('rejects a non-positive-integer maxRecords', () => {
-      expect(MemoryObservationStore.create({ maxRecords: 0 })).toFailWith(/positive integer/i);
-      expect(MemoryObservationStore.create({ maxRecords: 2.5 })).toFailWith(/positive integer/i);
-      expect(MemoryObservationStore.create({ maxRecords: -1 })).toFailWith(/positive integer/i);
-    });
-  });
-
-  describe('observe', () => {
-    test('retains records and tracks size + lastSeq', async () => {
-      const store = MemoryObservationStore.create().orThrow();
-      expect(await store.observe(obs({ seq: 1 }))).toSucceed();
-      expect(await store.observe(obs({ seq: 2 }))).toSucceed();
-      expect(store.size).toBe(2);
-      expect(store.lastSeq).toBe(2);
-    });
-
-    test('evicts the oldest beyond maxRecords, preserving lastSeq', async () => {
-      const store = MemoryObservationStore.create({ maxRecords: 2 }).orThrow();
-      await store.observe(obs({ seq: 1 }));
-      await store.observe(obs({ seq: 2 }));
-      await store.observe(obs({ seq: 3 }));
-      expect(store.size).toBe(2);
-      expect(store.lastSeq).toBe(3);
-      expect(seqs(store.query())).toEqual([2, 3]);
-    });
-  });
-
-  describe('query', () => {
-    let store: MemoryObservationStore;
-
-    beforeEach(async () => {
-      store = MemoryObservationStore.create().orThrow();
-      await store.observe(
-        obs({
-          seq: 1,
-          timestamp: 100,
-          phase: 'write',
-          scope: 'knowledge',
-          kind: 'knowledge',
-          outcome: 'success'
-        })
-      );
-      await store.observe(
-        obs({
-          seq: 2,
-          timestamp: 200,
-          phase: 'read',
-          scope: 'knowledge',
-          kind: 'knowledge',
-          outcome: 'failure'
-        })
-      );
-      await store.observe(
-        obs({ seq: 3, timestamp: 300, phase: 'delete', scope: 'other', kind: 'note', outcome: 'success' })
-      );
-    });
-
-    test('returns all records oldest-first with no criteria', () => {
-      expect(seqs(store.query())).toEqual([1, 2, 3]);
-    });
-
-    test('pages by sinceSeq', () => {
-      expect(seqs(store.query({ sinceSeq: 1 }))).toEqual([2, 3]);
-    });
-
-    test('limits to the most-recent N', () => {
-      expect(seqs(store.query({ limit: 2 }))).toEqual([2, 3]);
-    });
-
-    test('filters by timestamp window', () => {
-      expect(seqs(store.query({ since: 200 }))).toEqual([2, 3]);
-      expect(seqs(store.query({ until: 200 }))).toEqual([1, 2]);
-      expect(seqs(store.query({ since: 150, until: 250 }))).toEqual([2]);
-    });
-
-    test('filters by scope', () => {
-      expect(seqs(store.query({ scope: 'knowledge' as MemoryScopeKey }))).toEqual([1, 2]);
-    });
-
-    test('filters by kind', () => {
-      expect(seqs(store.query({ kind: 'note' as Kind }))).toEqual([3]);
-    });
-
-    test('filters by phase', () => {
-      expect(seqs(store.query({ phase: 'read' }))).toEqual([2]);
-    });
-
-    test('filters by outcome', () => {
-      expect(seqs(store.query({ outcome: 'failure' }))).toEqual([2]);
-    });
-
-    test('combines criteria with AND', () => {
-      expect(seqs(store.query({ scope: 'knowledge' as MemoryScopeKey, outcome: 'success' }))).toEqual([1]);
-    });
-  });
-
-  describe('clear', () => {
-    test('drops records but preserves lastSeq as a cursor floor', async () => {
-      const store = MemoryObservationStore.create().orThrow();
-      await store.observe(obs({ seq: 1 }));
-      await store.observe(obs({ seq: 2 }));
-      store.clear();
-      expect(store.size).toBe(0);
-      expect(store.lastSeq).toBe(2);
-      expect(store.query()).toEqual([]);
-    });
-  });
-});

package/src/test/unit/retrieve/fragmentSemanticRetriever.test.ts

@@ -1,163 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import '@fgv/ts-utils-jest';
-import { Result, fail, succeed } from '@fgv/ts-utils';
-import {
-  FRAGMENT_SEMANTIC_UNWIRED_MESSAGE,
-  FragmentSemanticRetriever,
-  IEdgeTarget,
-  IEmbeddedFragment,
-  IFragmentLocator,
-  IFragmentVectorIndex,
-  IVectorQueryHit,
-  MemoryId,
-  MemoryScopeKey
-} from '../../../index';
-
-function target(scope: string, id: string): IEdgeTarget {
-  return { scope: scope as MemoryScopeKey, id: id as MemoryId };
-}
-
-function loc(start: number, end: number): IFragmentLocator {
-  return { start, end };
-}
-
-function hit(scope: string, id: string, start: number, end: number, score: number): IVectorQueryHit {
-  return { target: target(scope, id), score, locator: loc(start, end) };
-}
-
-const okEmbed = (): Promise<Result<Float32Array>> => Promise.resolve(succeed(Float32Array.from([0.1, 0.2])));
-
-/** A scripted fragment index that records the args it was queried with. */
-class FakeFragmentIndex implements IFragmentVectorIndex {
-  public lastTopK: number | undefined;
-  public lastMaxPerRecord: number | undefined;
-  private readonly _hits: ReadonlyArray<IVectorQueryHit>;
-  private readonly _fail: boolean;
-  public constructor(hits: ReadonlyArray<IVectorQueryHit>, shouldFail: boolean = false) {
-    this._hits = hits;
-    this._fail = shouldFail;
-  }
-  public addFragments(
-    __t: IEdgeTarget,
-    fragments: ReadonlyArray<IEmbeddedFragment>
-  ): Promise<Result<number>> {
-    return Promise.resolve(succeed(fragments.length));
-  }
-  public remove(t: IEdgeTarget): Promise<Result<IEdgeTarget>> {
-    return Promise.resolve(succeed(t));
-  }
-  public query(
-    __vector: Float32Array,
-    topK: number,
-    maxPerRecord?: number
-  ): Promise<Result<ReadonlyArray<IVectorQueryHit>>> {
-    this.lastTopK = topK;
-    this.lastMaxPerRecord = maxPerRecord;
-    return Promise.resolve(this._fail ? fail('fragment backend down') : succeed(this._hits));
-  }
-}
-
-describe('FragmentSemanticRetriever', () => {
-  test('reports supportsFragmentRecall=false when no backend is wired', () => {
-    const r = FragmentSemanticRetriever.create({}).orThrow();
-    expect(r.capabilities.supportsFragmentRecall).toBe(false);
-  });
-
-  test('reports supportsFragmentRecall=true when a backend is wired', () => {
-    const r = FragmentSemanticRetriever.create({
-      backend: { fragmentIndex: new FakeFragmentIndex([]), embedQuery: okEmbed }
-    }).orThrow();
-    expect(r.capabilities.supportsFragmentRecall).toBe(true);
-  });
-
-  test('degrades loudly when no backend is wired — never a silent empty', async () => {
-    const r = FragmentSemanticRetriever.create({}).orThrow();
-    expect(await r.retrieve({ semantic: 'hi' })).toFailWith(FRAGMENT_SEMANTIC_UNWIRED_MESSAGE);
-  });
-
-  test('returns the per-fragment hits (target + locator + score) in backend order', async () => {
-    const hits = [hit('knowledge', 'doc-a', 0, 5, 0.9), hit('knowledge', 'doc-a', 20, 25, 0.4)];
-    const r = FragmentSemanticRetriever.create({
-      backend: { fragmentIndex: new FakeFragmentIndex(hits), embedQuery: okEmbed }
-    }).orThrow();
-    expect(await r.retrieve({ semantic: 'q' })).toSucceedAndSatisfy(
-      (result: ReadonlyArray<IVectorQueryHit>) => {
-        expect(result).toEqual(hits);
-        expect(result[0].locator).toEqual(loc(0, 5));
-        expect(result[1].locator).toEqual(loc(20, 25));
-      }
-    );
-  });
-
-  test('forwards topK and maxPerRecord to the fragment index', async () => {
-    const fragmentIndex = new FakeFragmentIndex([hit('knowledge', 'doc-a', 0, 5, 0.9)]);
-    const r = FragmentSemanticRetriever.create({
-      backend: { fragmentIndex, embedQuery: okEmbed }
-    }).orThrow();
-    expect(await r.retrieve({ semantic: 'q', topK: 3, maxPerRecord: 1 })).toSucceed();
-    expect(fragmentIndex.lastTopK).toBe(3);
-    expect(fragmentIndex.lastMaxPerRecord).toBe(1);
-  });
-
-  test('defaults topK to 10 and leaves maxPerRecord undefined when the query omits them', async () => {
-    const fragmentIndex = new FakeFragmentIndex([hit('knowledge', 'doc-a', 0, 5, 0.9)]);
-    const r = FragmentSemanticRetriever.create({
-      backend: { fragmentIndex, embedQuery: okEmbed }
-    }).orThrow();
-    expect(await r.retrieve({ semantic: 'q' })).toSucceed();
-    expect(fragmentIndex.lastTopK).toBe(10);
-    expect(fragmentIndex.lastMaxPerRecord).toBeUndefined();
-  });
-
-  test('fails loudly when the embedder fails', async () => {
-    const r = FragmentSemanticRetriever.create({
-      backend: {
-        fragmentIndex: new FakeFragmentIndex([]),
-        embedQuery: () => Promise.resolve(fail('no embed model'))
-      }
-    }).orThrow();
-    expect(await r.retrieve({ semantic: 'q' })).toFailWith(
-      /fragment recall: query embedding failed: no embed model/i
-    );
-  });
-
-  test('fails loudly when the fragment backend fails', async () => {
-    const r = FragmentSemanticRetriever.create({
-      backend: { fragmentIndex: new FakeFragmentIndex([], true), embedQuery: okEmbed }
-    }).orThrow();
-    expect(await r.retrieve({ semantic: 'q' })).toFailWith(
-      /fragment recall: fragment query failed: fragment backend down/i
-    );
-  });
-
-  test('normalizes a rejecting embedder into a Failure (never escapes as a rejection)', async () => {
-    const r = FragmentSemanticRetriever.create({
-      backend: {
-        fragmentIndex: new FakeFragmentIndex([]),
-        embedQuery: () => Promise.reject(new Error('embedder blew up'))
-      }
-    }).orThrow();
-    expect(await r.retrieve({ semantic: 'q' })).toFailWith(
-      /fragment recall: query embedding failed: .*embedder blew up/i
-    );
-  });
-
-  test('normalizes a rejecting fragment backend into a Failure', async () => {
-    const rejectingIndex: IFragmentVectorIndex = {
-      addFragments: (__t: IEdgeTarget, f: ReadonlyArray<IEmbeddedFragment>) =>
-        Promise.resolve(succeed(f.length)),
-      remove: (t: IEdgeTarget) => Promise.resolve(succeed(t)),
-      query: () => Promise.reject(new Error('socket hangup'))
-    };
-    const r = FragmentSemanticRetriever.create({
-      backend: { fragmentIndex: rejectingIndex, embedQuery: okEmbed }
-    }).orThrow();
-    expect(await r.retrieve({ semantic: 'q' })).toFailWith(
-      /fragment recall: fragment query failed: .*socket hangup/i
-    );
-  });
-});

package/src/test/unit/retrieve/linkTraversalRetriever.test.ts

@@ -1,329 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import '@fgv/ts-utils-jest';
-import {
-  IEdgeTarget,
-  IIndexedMemoryRecord,
-  IMemoryRecord,
-  Kind,
-  LinkTraversalRetriever,
-  LINK_TRAVERSAL_NO_SEED_MESSAGE,
-  LINK_TRAVERSAL_UNWIRED_MESSAGE,
-  MemoryId,
-  MemoryIndex,
-  MemoryScopeKey,
-  envelopeConverter
-} from '../../../index';
-
-const DEFAULT_SCOPE: string = 'experience';
-
-/** A link target authored either as a bare id (same-scope) or an explicit `(scope, id)`. */
-type LinkSpec = string | { readonly id: string; readonly scope: string };
-
-interface IEntrySpec {
-  readonly id: string;
-  readonly scope?: string;
-  readonly kind?: string;
-  readonly tags?: ReadonlyArray<string>;
-  readonly updated?: number;
-  readonly seq?: number;
-  readonly links?: ReadonlyArray<LinkSpec>;
-  readonly rank?: number;
-}
-
-/** A scope-qualified traversal seed (defaults to the fixture's default scope). */
-function seed(id: string, scope: string = DEFAULT_SCOPE): IEdgeTarget {
-  return { scope: scope as MemoryScopeKey, id: id as MemoryId };
-}
-
-function makeEntry(spec: IEntrySpec): IIndexedMemoryRecord {
-  const scope: string = spec.scope ?? DEFAULT_SCOPE;
-  const record: IMemoryRecord<unknown> = {
-    envelope: envelopeConverter
-      .convert({
-        id: spec.id,
-        entityId: spec.id,
-        kind: spec.kind ?? 'experience',
-        tags: spec.tags ?? [],
-        // A bare link id defaults its target scope to the source record's own
-        // scope (the same-conversation case); an object carries an explicit scope.
-        links: (spec.links ?? []).map((l) =>
-          typeof l === 'string'
-            ? { type: 'rel', target: { scope, id: l } }
-            : { type: 'rel', target: { scope: l.scope, id: l.id } }
-        ),
-        created: 0,
-        updated: spec.updated ?? 0,
-        seq: spec.seq ?? 0,
-        contentHash: 'h',
-        ...(spec.rank !== undefined ? { rank: spec.rank } : {}),
-        provenance: { source: 'agent' }
-      })
-      .orThrow(),
-    body: `body-${spec.id}`
-  };
-  return { scope: scope as MemoryScopeKey, record };
-}
-
-function buildIndex(specs: ReadonlyArray<IEntrySpec>): MemoryIndex {
-  const index = MemoryIndex.create().orThrow();
-  index.rebuild(specs.map(makeEntry)).orThrow();
-  return index;
-}
-
-function ids(records: ReadonlyArray<IMemoryRecord<unknown>>): string[] {
-  return records.map((r) => r.envelope.id as string);
-}
-
-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: seed('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: seed('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: seed('a'), hops: 2 })).toSucceedAndSatisfy((records) => {
-        expect(ids(records).sort()).toEqual(['b', 'c']);
-      });
-    });
-  });
-
-  describe('orderBy axis', () => {
-    function seedIndex(): MemoryIndex {
-      // Seed 'a' links to three ranked neighbors. `rank` and `updated` are
-      // deliberately INVERTED so the rank order (n3,n2,n1) is the exact reverse of
-      // the recency order (n1,n2,n3) — proving orderBy actually re-sorts.
-      return buildIndex([
-        { id: 'a', links: ['n1', 'n3', 'n2'] },
-        { id: 'n1', rank: 1, updated: 300, seq: 1 },
-        { id: 'n3', rank: 3, updated: 100, seq: 3 },
-        { id: 'n2', rank: 2, updated: 200, seq: 2 }
-      ]);
-    }
-
-    test("orderBy 'rank' orders reached records by rank descending", async () => {
-      const retriever = LinkTraversalRetriever.create(seedIndex()).orThrow();
-      expect(await retriever.retrieve({ linkedFrom: seed('a'), orderBy: 'rank' })).toSucceedAndSatisfy(
-        (records) => {
-          expect(ids(records)).toEqual(['n3', 'n2', 'n1']);
-        }
-      );
-    });
-
-    test('orderBy absent is unchanged recency order', async () => {
-      const retriever = LinkTraversalRetriever.create(seedIndex()).orThrow();
-      expect(await retriever.retrieve({ linkedFrom: seed('a') })).toSucceedAndSatisfy((records) => {
-        // Recency: most-recently-updated first → n1(300), n2(200), n3(100).
-        expect(ids(records)).toEqual(['n1', 'n2', 'n3']);
-      });
-    });
-
-    test("orderBy 'rank' composes with { limit, offset }", async () => {
-      const retriever = LinkTraversalRetriever.create(seedIndex()).orThrow();
-      expect(
-        await retriever.retrieve({ linkedFrom: seed('a'), orderBy: 'rank', limit: 1, offset: 1 })
-      ).toSucceedAndSatisfy((records) => {
-        expect(ids(records)).toEqual(['n2']);
-      });
-    });
-  });
-
-  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: seed('target') })).toSucceedAndSatisfy((records) => {
-        expect(ids(records)).toEqual(['a', 'b']);
-      });
-    });
-
-    test('reaches ONLY the same-scope inbound source when a TARGET stem is reused across scopes', async () => {
-      // 'shared' exists in scope a and scope b; src-a@a links {a, shared} and
-      // src-b@b links {b, shared}. Seeding linkedTo {a, shared} must reach ONLY
-      // src-a — backlinks disambiguate on the target's (scope, id), not a bare id.
-      const index = buildIndex([
-        { id: 'src-a', scope: 'a', links: ['shared'], tags: ['src-a'] },
-        { id: 'src-b', scope: 'b', links: ['shared'], tags: ['src-b'] },
-        { id: 'shared', scope: 'a' },
-        { id: 'shared', scope: 'b' }
-      ]);
-      const retriever = LinkTraversalRetriever.create(index).orThrow();
-      expect(await retriever.retrieve({ linkedTo: seed('shared', 'a') })).toSucceedAndSatisfy((records) => {
-        expect(records).toHaveLength(1);
-        expect(records[0].envelope.tags).toEqual(['src-a']);
-      });
-      // Symmetric: seeding the b-scope target reaches only src-b.
-      expect(await retriever.retrieve({ linkedTo: seed('shared', 'b') })).toSucceedAndSatisfy((records) => {
-        expect(records).toHaveLength(1);
-        expect(records[0].envelope.tags).toEqual(['src-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: seed('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: seed('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: [{ id: 'doc-1', scope: 'knowledge' }]
-      },
-      { id: 'doc-1', scope: 'knowledge', kind: 'knowledge' }
-    ]);
-    const retriever = LinkTraversalRetriever.create(index).orThrow();
-    expect(
-      await retriever.retrieve({ linkedFrom: seed('turn-5', 'conversations/conv-1') })
-    ).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: seed('a'), kind: 'keep' as unknown as Kind })
-      ).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: seed('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: seed('missing') })).toSucceedWith([]);
-    });
-
-    test('reaches ONLY the same-scope target when an id is reused across scopes', async () => {
-      // 'seed' (scope a) links a bare 'dup' → the edge target is {scope a, id dup}.
-      // Two records share the stem 'dup' (scopes a and b); the scoped edge must
-      // reach ONLY dup@a, never dup@b — the whole point of scope-qualified targets.
-      const index = buildIndex([
-        { id: 'seed', scope: 'a', links: ['dup'] },
-        { id: 'dup', scope: 'a', tags: ['in-a'] },
-        { id: 'dup', scope: 'b', tags: ['in-b'] }
-      ]);
-      const retriever = LinkTraversalRetriever.create(index).orThrow();
-      expect(await retriever.retrieve({ linkedFrom: seed('seed', 'a') })).toSucceedAndSatisfy((records) => {
-        expect(records).toHaveLength(1);
-        expect(records[0].envelope.tags).toEqual(['in-a']);
-      });
-    });
-
-    test('an explicit cross-scope edge reaches the other scope', async () => {
-      // The same fixture, but the edge names dup@b explicitly → traversal follows
-      // it to the b-scope record, proving explicit scope is honored verbatim.
-      const index = buildIndex([
-        { id: 'seed', scope: 'a', links: [{ id: 'dup', scope: 'b' }] },
-        { id: 'dup', scope: 'a', tags: ['in-a'] },
-        { id: 'dup', scope: 'b', tags: ['in-b'] }
-      ]);
-      const retriever = LinkTraversalRetriever.create(index).orThrow();
-      expect(await retriever.retrieve({ linkedFrom: seed('seed', 'a') })).toSucceedAndSatisfy((records) => {
-        expect(records).toHaveLength(1);
-        expect(records[0].envelope.tags).toEqual(['in-b']);
-      });
-    });
-  });
-
-  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: seed('a') })).toSucceed();
-  });
-});