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

package/src/test/unit/converters/envelopeConverter.test.ts

@@ -1,418 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import '@fgv/ts-utils-jest';
-import { Converters } from '@fgv/ts-utils';
-import {
-  BodyConverterRegistry,
-  edgeConverter,
-  edgeTargetConverter,
-  envelopeConverter,
-  envelopeYamlConverter,
-  joinFrontmatter,
-  parseMemoryFile,
-  provenanceConverter,
-  serializeMemoryFile,
-  splitFrontmatter,
-  temporalConverter
-} from '../../../packlets/converters';
-import { IMemoryEnvelope, Kind } from '../../../packlets/types';
-
-const validEnvelopeObject: Record<string, unknown> = {
-  id: 'intro-to-rust',
-  entityId: 'intro-to-rust',
-  kind: 'knowledge',
-  tags: ['rust', 'systems'],
-  links: [{ type: 'related', target: { scope: 'knowledge', id: 'ownership' } }],
-  created: 1000,
-  updated: 2000,
-  seq: 5,
-  contentHash: 'crc-abc',
-  provenance: { source: 'agent', by: 'curator' }
-};
-
-describe('provenanceConverter', () => {
-  test('validates the known fields', () => {
-    expect(
-      provenanceConverter.convert({ source: 'human', by: 'erik', model: 'gpt', confidence: 0.9 })
-    ).toSucceedWith({ source: 'human', by: 'erik', model: 'gpt', confidence: 0.9 });
-  });
-
-  test('preserves opaque extension keys verbatim', () => {
-    expect(
-      provenanceConverter.convert({ source: 'agent', sentiment: { score: 0.5 }, epistemic: 'belief' })
-    ).toSucceedAndSatisfy((p) => {
-      expect(p.source).toBe('agent');
-      expect(p.sentiment).toEqual({ score: 0.5 });
-      expect(p.epistemic).toBe('belief');
-    });
-  });
-
-  test('accepts an arbitrary source string (open vocabulary)', () => {
-    expect(provenanceConverter.convert({ source: 'host-ingest' })).toSucceedWith({ source: 'host-ingest' });
-  });
-
-  test('validates a scope-qualified derivedFrom (nested { scope, id })', () => {
-    expect(
-      provenanceConverter.convert({
-        source: 'host-ingest',
-        derivedFrom: { scope: 'conversations/conv-a', id: 'turn-3' }
-      })
-    ).toSucceedAndSatisfy((p) => {
-      expect(p.derivedFrom).toEqual({ scope: 'conversations/conv-a', id: 'turn-3' });
-    });
-  });
-
-  test('rejects a bare-string derivedFrom (the pre-scoped format)', () => {
-    expect(provenanceConverter.convert({ source: 'host-ingest', derivedFrom: 'turn-3' })).toFail();
-  });
-
-  test('rejects a derivedFrom missing scope', () => {
-    expect(provenanceConverter.convert({ source: 'host-ingest', derivedFrom: { id: 'turn-3' } })).toFailWith(
-      /scope/i
-    );
-  });
-
-  test('rejects a derivedFrom missing id', () => {
-    expect(
-      provenanceConverter.convert({ source: 'host-ingest', derivedFrom: { scope: 'conversations/conv-a' } })
-    ).toFailWith(/id/i);
-  });
-
-  test('fails when source is missing', () => {
-    expect(provenanceConverter.convert({ by: 'erik' })).toFail();
-  });
-
-  test('fails on a non-object', () => {
-    expect(provenanceConverter.convert('nope')).toFail();
-  });
-});
-
-describe('edgeTargetConverter', () => {
-  test('validates a scope-qualified target', () => {
-    expect(edgeTargetConverter.convert({ scope: 'conversations/conv-a', id: 'turn-3' })).toSucceedAndSatisfy(
-      (t) => {
-        expect(t).toEqual({ scope: 'conversations/conv-a', id: 'turn-3' });
-      }
-    );
-  });
-
-  test('rejects a target missing scope', () => {
-    expect(edgeTargetConverter.convert({ id: 'turn-3' })).toFailWith(/scope/i);
-  });
-
-  test('rejects a target missing id', () => {
-    expect(edgeTargetConverter.convert({ scope: 'conversations/conv-a' })).toFailWith(/id/i);
-  });
-
-  test('rejects a bare-string target (the pre-scoped format)', () => {
-    expect(edgeTargetConverter.convert('turn-3')).toFail();
-  });
-});
-
-describe('edgeConverter', () => {
-  test('validates a full attributed edge', () => {
-    expect(
-      edgeConverter.convert({
-        type: 'mtm-ref',
-        target: { scope: 'conversations/conv-a', id: 'turn-3' },
-        confidence: 0.8,
-        provenance: { source: 'agent' },
-        valid_at: 100,
-        invalid_at: 200
-      })
-    ).toSucceedAndSatisfy((edge) => {
-      expect(edge.type).toBe('mtm-ref');
-      expect(edge.target).toEqual({ scope: 'conversations/conv-a', id: 'turn-3' });
-      expect(edge.confidence).toBe(0.8);
-      expect(edge.provenance).toEqual({ source: 'agent' });
-      expect(edge.valid_at).toBe(100);
-      expect(edge.invalid_at).toBe(200);
-    });
-  });
-
-  test('validates a minimal edge', () => {
-    expect(
-      edgeConverter.convert({ type: 'related', target: { scope: 'knowledge', id: 'ownership' } })
-    ).toSucceedAndSatisfy((edge) => {
-      expect(edge.type).toBe('related');
-      expect(edge.target).toEqual({ scope: 'knowledge', id: 'ownership' });
-      expect(edge.confidence).toBeUndefined();
-    });
-  });
-
-  test('accepts a null invalid_at (still valid)', () => {
-    expect(
-      edgeConverter.convert({ type: 'related', target: { scope: 'knowledge', id: 'x' }, invalid_at: null })
-    ).toSucceedAndSatisfy((edge) => {
-      expect(edge.invalid_at).toBeNull();
-    });
-  });
-
-  test('fails when invalid_at is neither a number nor null', () => {
-    expect(
-      edgeConverter.convert({ type: 'related', target: { scope: 'knowledge', id: 'x' }, invalid_at: 'soon' })
-    ).toFail();
-  });
-
-  test('fails when target is missing', () => {
-    expect(edgeConverter.convert({ type: 'related' })).toFail();
-  });
-
-  test('fails when target is a bare string (rejects the pre-scoped format)', () => {
-    expect(edgeConverter.convert({ type: 'related', target: 'ownership' })).toFail();
-  });
-});
-
-describe('temporalConverter', () => {
-  test('validates a temporal block', () => {
-    expect(temporalConverter.convert({ valid_at: 1, invalid_at: null })).toSucceedWith({
-      valid_at: 1,
-      invalid_at: null
-    });
-  });
-
-  test('validates an empty temporal block', () => {
-    expect(temporalConverter.convert({})).toSucceedWith({});
-  });
-});
-
-describe('envelopeConverter', () => {
-  test('validates a full envelope without optional blocks', () => {
-    expect(envelopeConverter.convert(validEnvelopeObject)).toSucceedAndSatisfy((envelope) => {
-      expect(envelope.id).toBe('intro-to-rust');
-      expect(envelope.tags).toEqual(['rust', 'systems']);
-      expect(envelope.links).toHaveLength(1);
-      expect(envelope.temporal).toBeUndefined();
-      expect(envelope.embeddingRef).toBeUndefined();
-    });
-  });
-
-  test('validates a temporal envelope with a string embeddingRef', () => {
-    expect(
-      envelopeConverter.convert({
-        ...validEnvelopeObject,
-        temporal: { valid_at: 10 },
-        embeddingRef: 'vec-1'
-      })
-    ).toSucceedAndSatisfy((envelope) => {
-      expect(envelope.temporal).toEqual({ valid_at: 10 });
-      expect(envelope.embeddingRef).toBe('vec-1');
-    });
-  });
-
-  test('accepts a null embeddingRef (not embedded)', () => {
-    expect(envelopeConverter.convert({ ...validEnvelopeObject, embeddingRef: null })).toSucceedAndSatisfy(
-      (envelope) => {
-        expect(envelope.embeddingRef).toBeNull();
-      }
-    );
-  });
-
-  test('fails when embeddingRef is neither a string nor null', () => {
-    expect(envelopeConverter.convert({ ...validEnvelopeObject, embeddingRef: 42 })).toFail();
-  });
-
-  test('rank is absent when not present', () => {
-    expect(envelopeConverter.convert(validEnvelopeObject)).toSucceedAndSatisfy((envelope) => {
-      expect(envelope.rank).toBeUndefined();
-    });
-  });
-
-  test('validates and preserves a numeric rank', () => {
-    expect(envelopeConverter.convert({ ...validEnvelopeObject, rank: 42 })).toSucceedAndSatisfy(
-      (envelope) => {
-        expect(envelope.rank).toBe(42);
-      }
-    );
-  });
-
-  test('serialize/parse round-trips rank through frontmatter', () => {
-    const registry = BodyConverterRegistry.create().orThrow();
-    registry.register('knowledge' as Kind, Converters.string);
-    const envelope = envelopeConverter.convert({ ...validEnvelopeObject, rank: 7 }).orThrow();
-    const file = serializeMemoryFile(envelope, 'body').orThrow();
-    expect(parseMemoryFile(file, registry)).toSucceedAndSatisfy((record) => {
-      expect(record.envelope.rank).toBe(7);
-    });
-  });
-
-  test('fails when rank is not a number', () => {
-    expect(envelopeConverter.convert({ ...validEnvelopeObject, rank: 'high' })).toFail();
-  });
-
-  test('fails when a required field is missing', () => {
-    const missing: Record<string, unknown> = { ...validEnvelopeObject };
-    delete missing.contentHash;
-    expect(envelopeConverter.convert(missing)).toFail();
-  });
-});
-
-describe('envelopeYamlConverter', () => {
-  test('parses an envelope from a YAML string', () => {
-    const yaml = serializeMemoryFile(
-      envelopeConverter.convert(validEnvelopeObject).orThrow(),
-      'body text'
-    ).orThrow();
-    const frontmatter = splitFrontmatter(yaml).orThrow().frontmatter;
-    expect(envelopeYamlConverter.convert(frontmatter)).toSucceedAndSatisfy((envelope) => {
-      expect(envelope.id).toBe('intro-to-rust');
-    });
-  });
-
-  test('fails on a YAML string that is not an object', () => {
-    expect(envelopeYamlConverter.convert('just a scalar')).toFail();
-  });
-});
-
-describe('splitFrontmatter / joinFrontmatter', () => {
-  test('splits a well-formed memory file', () => {
-    const raw = '---\nid: x\nkind: knowledge\n---\nThe body.\nSecond line.';
-    expect(splitFrontmatter(raw)).toSucceedWith({
-      frontmatter: 'id: x\nkind: knowledge',
-      body: 'The body.\nSecond line.'
-    });
-  });
-
-  test('strips trailing CR so CRLF-authored files parse identically to LF', () => {
-    const raw = '---\r\nid: x\r\nkind: knowledge\r\n---\r\nThe body.\r\nSecond line.';
-    expect(splitFrontmatter(raw)).toSucceedWith({
-      frontmatter: 'id: x\nkind: knowledge',
-      body: 'The body.\nSecond line.'
-    });
-  });
-
-  test('fails when the opening delimiter is missing', () => {
-    expect(splitFrontmatter('no frontmatter here')).toFailWith(/missing opening frontmatter delimiter/i);
-  });
-
-  test('fails when the closing delimiter is missing', () => {
-    expect(splitFrontmatter('---\nid: x\nstill going')).toFailWith(/missing closing frontmatter delimiter/i);
-  });
-
-  test('join adds a trailing newline to the frontmatter when absent', () => {
-    expect(joinFrontmatter('id: x', 'body')).toBe('---\nid: x\n---\nbody');
-  });
-
-  test('join does not double the trailing newline when present', () => {
-    expect(joinFrontmatter('id: x\n', 'body')).toBe('---\nid: x\n---\nbody');
-  });
-
-  test('split and join round-trip', () => {
-    const raw = '---\nid: x\n---\nbody content';
-    const parts = splitFrontmatter(raw).orThrow();
-    expect(joinFrontmatter(parts.frontmatter, parts.body)).toBe(raw);
-  });
-});
-
-describe('parseMemoryFile / serializeMemoryFile', () => {
-  let registry: BodyConverterRegistry;
-  const knowledgeKind: Kind = 'knowledge' as Kind;
-
-  beforeEach(() => {
-    registry = BodyConverterRegistry.create().orThrow();
-    registry.register(knowledgeKind, Converters.string);
-  });
-
-  test('serializes then parses a record round-trip', () => {
-    const envelope = envelopeConverter.convert(validEnvelopeObject).orThrow();
-    const file = serializeMemoryFile(envelope, 'The knowledge body.').orThrow();
-    expect(parseMemoryFile(file, registry)).toSucceedAndSatisfy((record) => {
-      expect(record.envelope.id).toBe('intro-to-rust');
-      expect(record.body).toBe('The knowledge body.');
-    });
-  });
-
-  test('round-trips a scope-qualified edge target through the frontmatter intact', () => {
-    const envelope = envelopeConverter
-      .convert({
-        ...validEnvelopeObject,
-        links: [{ type: 'mtm-ref', target: { scope: 'conversations/conv-a', id: 'turn-3' } }]
-      })
-      .orThrow();
-    const file = serializeMemoryFile(envelope, 'body').orThrow();
-    // On-wire the target is a nested object, NOT a bare scalar.
-    expect(file).toMatch(/scope: conversations\/conv-a/);
-    expect(file).toMatch(/id: turn-3/);
-    expect(parseMemoryFile(file, registry)).toSucceedAndSatisfy((record) => {
-      expect(record.envelope.links).toEqual([
-        { type: 'mtm-ref', target: { scope: 'conversations/conv-a', id: 'turn-3' } }
-      ]);
-      // Serializing the reparsed record reproduces byte-identical output.
-      expect(serializeMemoryFile(record.envelope, record.body as string)).toSucceedWith(file);
-    });
-  });
-
-  test('round-trips a scope-qualified provenance.derivedFrom through the frontmatter intact', () => {
-    const envelope = envelopeConverter
-      .convert({
-        ...validEnvelopeObject,
-        provenance: {
-          source: 'host-ingest',
-          derivedFrom: { scope: 'conversations/conv-a', id: 'turn-3' }
-        }
-      })
-      .orThrow();
-    const file = serializeMemoryFile(envelope, 'body').orThrow();
-    // On-wire the back-reference is a nested object, NOT a bare scalar.
-    expect(file).toMatch(/scope: conversations\/conv-a/);
-    expect(parseMemoryFile(file, registry)).toSucceedAndSatisfy((record) => {
-      expect(record.envelope.provenance.derivedFrom).toEqual({
-        scope: 'conversations/conv-a',
-        id: 'turn-3'
-      });
-      expect(serializeMemoryFile(record.envelope, record.body as string)).toSucceedWith(file);
-    });
-  });
-
-  test('two records whose derivedFrom share a stem across scopes round-trip as distinct scoped refs', () => {
-    // Same idStem ('turn-3'), different scopes — exactly the ambiguity a bare
-    // MemoryId could not disambiguate. Each must round-trip to ITS OWN scope.
-    const makeFile = (scope: string): string => {
-      const envelope = envelopeConverter
-        .convert({
-          ...validEnvelopeObject,
-          provenance: { source: 'host-ingest', derivedFrom: { scope, id: 'turn-3' } }
-        })
-        .orThrow();
-      return serializeMemoryFile(envelope, 'body').orThrow();
-    };
-    const fileA = makeFile('conversations/conv-a');
-    const fileB = makeFile('conversations/conv-b');
-    expect(fileA).not.toBe(fileB);
-    expect(parseMemoryFile(fileA, registry)).toSucceedAndSatisfy((record) => {
-      expect(record.envelope.provenance.derivedFrom).toEqual({
-        scope: 'conversations/conv-a',
-        id: 'turn-3'
-      });
-    });
-    expect(parseMemoryFile(fileB, registry)).toSucceedAndSatisfy((record) => {
-      expect(record.envelope.provenance.derivedFrom).toEqual({
-        scope: 'conversations/conv-b',
-        id: 'turn-3'
-      });
-    });
-  });
-
-  test('fails when the frontmatter cannot be split', () => {
-    expect(parseMemoryFile('no delimiters', registry)).toFailWith(/missing opening frontmatter delimiter/i);
-  });
-
-  test('fails with envelope context when the envelope is invalid', () => {
-    const file = '---\nid: x\n---\nbody';
-    expect(parseMemoryFile(file, registry)).toFailWith(/invalid envelope/i);
-  });
-
-  test('fails with body context when the body fails the registered converter', () => {
-    const envelope = envelopeConverter.convert({ ...validEnvelopeObject, kind: 'unregistered' }).orThrow();
-    const file = serializeMemoryFile(envelope, 'body').orThrow();
-    expect(parseMemoryFile(file, registry)).toFailWith(/invalid body.*no converter registered/i);
-  });
-
-  test('serialize fails (with id context) when the envelope cannot be dumped to YAML', () => {
-    const unserializable = { ...validEnvelopeObject, weird: BigInt(10) } as unknown as IMemoryEnvelope;
-    expect(serializeMemoryFile(unserializable, 'body')).toFailWith(/failed to serialize envelope/i);
-  });
-});

package/src/test/unit/index/memoryIndex.test.ts

@@ -1,272 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import '@fgv/ts-utils-jest';
-import {
-  IEdgeTarget,
-  IIndexedMemoryRecord,
-  IMemoryRecord,
-  Kind,
-  MemoryId,
-  MemoryIndex,
-  MemoryScopeKey,
-  Tag,
-  envelopeConverter,
-  rankCompare
-} from '../../../index';
-
-/**
- * The scope every link target in this fixture lives under. Links are authored as
- * bare id strings and resolved to `{ scope: LINK_TARGET_SCOPE, id }`, so the
- * cross-scope source tests can share one target while their sources differ.
- */
-const LINK_TARGET_SCOPE: string = 'knowledge';
-
-/** A scope-qualified backlink-target query for the fixed link-target scope. */
-function bt(id: string): IEdgeTarget {
-  return { scope: LINK_TARGET_SCOPE as MemoryScopeKey, id: id as MemoryId };
-}
-
-/** Extract the bare ids from a set of scope-qualified targets (backlink results). */
-function targetIds(targets: ReadonlyArray<IEdgeTarget>): string[] {
-  return targets.map((t) => t.id as string);
-}
-
-interface IRecordSpec {
-  readonly id: string;
-  readonly scope?: string;
-  readonly kind?: string;
-  readonly tags?: ReadonlyArray<string>;
-  readonly links?: ReadonlyArray<string>;
-  readonly updated?: number;
-  readonly seq?: number;
-  readonly rank?: number;
-}
-
-function makeEntry(spec: IRecordSpec): IIndexedMemoryRecord {
-  const record: IMemoryRecord<unknown> = {
-    envelope: envelopeConverter
-      .convert({
-        id: spec.id,
-        entityId: spec.id,
-        kind: spec.kind ?? 'knowledge',
-        tags: spec.tags ?? [],
-        links: (spec.links ?? []).map((target) => ({
-          type: 'rel',
-          target: { scope: LINK_TARGET_SCOPE, id: target }
-        })),
-        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: (spec.scope ?? 'knowledge') as MemoryScopeKey, record };
-}
-
-function ids(records: ReadonlyArray<IMemoryRecord<unknown>>): ReadonlyArray<string> {
-  return records.map((r) => r.envelope.id as string);
-}
-
-describe('MemoryIndex', () => {
-  let index: MemoryIndex;
-
-  beforeEach(() => {
-    index = MemoryIndex.create().orThrow();
-  });
-
-  describe('create', () => {
-    test('starts empty', () => {
-      expect(index.entries()).toHaveLength(0);
-      expect(index.byKind('knowledge' as Kind)).toHaveLength(0);
-      expect(index.byTag('any' as Tag)).toHaveLength(0);
-      expect(index.byRecency()).toHaveLength(0);
-      expect(index.backlinks(bt('none'))).toHaveLength(0);
-    });
-  });
-
-  describe('rebuild', () => {
-    test('indexes every entry and reports the count', () => {
-      const entries = [
-        makeEntry({ id: 'a', tags: ['x'], links: ['b'] }),
-        makeEntry({ id: 'b', tags: ['x', 'y'] })
-      ];
-      expect(index.rebuild(entries)).toSucceedWith(2);
-      expect(index.entries()).toHaveLength(2);
-      expect([...ids(index.byKind('knowledge' as Kind))].sort()).toEqual(['a', 'b']);
-      expect([...ids(index.byTag('x' as Tag))].sort()).toEqual(['a', 'b']);
-      expect(ids(index.byTag('y' as Tag))).toEqual(['b']);
-      expect(targetIds(index.backlinks(bt('b')))).toEqual(['a']);
-    });
-
-    test('clears prior state', () => {
-      index.rebuild([makeEntry({ id: 'a', tags: ['x'] })]).orThrow();
-      expect(index.rebuild([makeEntry({ id: 'c', tags: ['z'] })])).toSucceedWith(1);
-      expect(ids(index.entries().map((e) => e.record))).toEqual(['c']);
-      expect(index.byTag('x' as Tag)).toHaveLength(0);
-    });
-  });
-
-  describe('patch', () => {
-    test('put inserts a new entry and returns it', () => {
-      const entry = makeEntry({ id: 'a', tags: ['x'], links: ['b'] });
-      expect(index.patch('put', entry)).toSucceedWith(entry);
-      expect(ids(index.byKind('knowledge' as Kind))).toEqual(['a']);
-      expect(targetIds(index.backlinks(bt('b')))).toEqual(['a']);
-    });
-
-    test('put on an existing key replaces stale associations', () => {
-      index.patch('put', makeEntry({ id: 'a', kind: 'knowledge', tags: ['old'], links: ['b'] })).orThrow();
-      index.patch('put', makeEntry({ id: 'a', kind: 'note', tags: ['new'], links: ['c'] })).orThrow();
-      expect(index.entries()).toHaveLength(1);
-      expect(index.byTag('old' as Tag)).toHaveLength(0);
-      expect(ids(index.byTag('new' as Tag))).toEqual(['a']);
-      expect(index.byKind('knowledge' as Kind)).toHaveLength(0);
-      expect(ids(index.byKind('note' as Kind))).toEqual(['a']);
-      expect(index.backlinks(bt('b'))).toHaveLength(0);
-      expect(targetIds(index.backlinks(bt('c')))).toEqual(['a']);
-    });
-
-    test('delete removes the entry and its associations', () => {
-      const entry = makeEntry({ id: 'a', tags: ['x'], links: ['b'] });
-      index.patch('put', entry).orThrow();
-      expect(index.patch('delete', entry)).toSucceedWith(entry);
-      expect(index.entries()).toHaveLength(0);
-      expect(index.byTag('x' as Tag)).toHaveLength(0);
-      expect(index.backlinks(bt('b'))).toHaveLength(0);
-    });
-
-    test('delete of an absent key is a no-op that still succeeds', () => {
-      const entry = makeEntry({ id: 'ghost' });
-      expect(index.patch('delete', entry)).toSucceedWith(entry);
-      expect(index.entries()).toHaveLength(0);
-    });
-
-    test('distinguishes entries with the same id across scopes', () => {
-      index.patch('put', makeEntry({ id: 'turn-0', scope: 'conversations/c1' })).orThrow();
-      index.patch('put', makeEntry({ id: 'turn-0', scope: 'conversations/c2' })).orThrow();
-      expect(index.entries()).toHaveLength(2);
-    });
-  });
-
-  describe('byRecency', () => {
-    test('orders most-recently-updated first, breaking ties by seq', () => {
-      index
-        .rebuild([
-          makeEntry({ id: 'old', updated: 100, seq: 1 }),
-          makeEntry({ id: 'newest', updated: 300, seq: 3 }),
-          makeEntry({ id: 'tie-lo', updated: 200, seq: 4 }),
-          makeEntry({ id: 'tie-hi', updated: 200, seq: 9 })
-        ])
-        .orThrow();
-      expect(ids(index.byRecency())).toEqual(['newest', 'tie-hi', 'tie-lo', 'old']);
-    });
-  });
-
-  describe('byRank', () => {
-    test('orders by rank descending, absent-rank records last, recency tiebreak', () => {
-      index
-        .rebuild([
-          makeEntry({ id: 'mid', rank: 5, updated: 100, seq: 1 }),
-          makeEntry({ id: 'top', rank: 9, updated: 100, seq: 2 }),
-          makeEntry({ id: 'tie-lo', rank: 3, updated: 200, seq: 4 }),
-          makeEntry({ id: 'tie-hi', rank: 3, updated: 200, seq: 9 }),
-          makeEntry({ id: 'unranked-old', updated: 100, seq: 5 }),
-          makeEntry({ id: 'unranked-new', updated: 400, seq: 6 })
-        ])
-        .orThrow();
-      // ranked (desc): top(9), mid(5), tie-hi(3,seq9), tie-lo(3,seq4);
-      // then unranked by recency: unranked-new(updated400), unranked-old(updated100).
-      expect(ids(index.byRank())).toEqual(['top', 'mid', 'tie-hi', 'tie-lo', 'unranked-new', 'unranked-old']);
-    });
-
-    test('is empty on an empty index', () => {
-      expect(index.byRank()).toHaveLength(0);
-    });
-
-    test('sorts a ranked record ahead of an earlier-listed absent-rank record', () => {
-      // Input lists the absent-rank record first so the sort compares (ranked, absent),
-      // exercising the ranked-before-absent direction of the comparator.
-      index
-        .rebuild([
-          makeEntry({ id: 'unranked', updated: 100, seq: 1 }),
-          makeEntry({ id: 'ranked', rank: 5, updated: 100, seq: 2 })
-        ])
-        .orThrow();
-      expect(ids(index.byRank())).toEqual(['ranked', 'unranked']);
-    });
-
-    test('orders two absent-rank records by recency alone', () => {
-      index
-        .rebuild([makeEntry({ id: 'a', updated: 100, seq: 1 }), makeEntry({ id: 'b', updated: 300, seq: 2 })])
-        .orThrow();
-      expect(ids(index.byRank())).toEqual(['b', 'a']);
-    });
-
-    test("index byRank agrees pairwise with the retrieve packlet's rankCompare", () => {
-      // Guard against the two hand-duplicated comparators (index `_compareByRank`
-      // and retrieve `rankCompare`) drifting: a future tie-break edit to one that
-      // diverges from the other is caught here on a shared mixed fixture.
-      const fixture = [
-        makeEntry({ id: 'r-top', rank: 9, updated: 100, seq: 1 }),
-        makeEntry({ id: 'r-mid', rank: 5, updated: 400, seq: 2 }),
-        makeEntry({ id: 'r-tie-a', rank: 3, updated: 200, seq: 3 }),
-        makeEntry({ id: 'r-tie-b', rank: 3, updated: 200, seq: 8 }),
-        makeEntry({ id: 'absent-old', updated: 100, seq: 4 }),
-        makeEntry({ id: 'absent-new', updated: 500, seq: 5 })
-      ];
-      index.rebuild(fixture).orThrow();
-      const viaIndex = ids(index.byRank());
-      const viaRankCompare = ids(fixture.map((e) => e.record).sort(rankCompare));
-      expect(viaIndex).toEqual(viaRankCompare);
-      // And the shared expected ordering is what both must produce.
-      expect(viaIndex).toEqual(['r-top', 'r-mid', 'r-tie-b', 'r-tie-a', 'absent-new', 'absent-old']);
-    });
-  });
-
-  describe('backlinks', () => {
-    test('aggregates multiple sources pointing at one target', () => {
-      index
-        .rebuild([makeEntry({ id: 'a', links: ['target'] }), makeEntry({ id: 'b', links: ['target'] })])
-        .orThrow();
-      expect(targetIds(index.backlinks(bt('target'))).sort()).toEqual(['a', 'b']);
-    });
-
-    test('drops the target set once the last source is removed', () => {
-      const a = makeEntry({ id: 'a', links: ['target'] });
-      index.patch('put', a).orThrow();
-      index.patch('delete', a).orThrow();
-      expect(index.backlinks(bt('target'))).toHaveLength(0);
-    });
-
-    test('tracks same-id sources across scopes independently', () => {
-      // Two distinct records that share the id 'a' under different scopes, both
-      // linking 'target'. Removing one must NOT drop the other's inbound edge.
-      const a1 = makeEntry({ id: 'a', scope: 'conversations/c1', links: ['target'] });
-      const a2 = makeEntry({ id: 'a', scope: 'conversations/c2', links: ['target'] });
-      index.patch('put', a1).orThrow();
-      index.patch('put', a2).orThrow();
-      expect(targetIds(index.backlinks(bt('target')))).toEqual(['a', 'a']);
-      index.patch('delete', a1).orThrow();
-      expect(targetIds(index.backlinks(bt('target')))).toEqual(['a']);
-    });
-  });
-
-  describe('duplicate associations', () => {
-    test('a record with duplicate tags and links is cleaned up exactly once on delete', () => {
-      const entry = makeEntry({ id: 'a', tags: ['dup', 'dup'], links: ['t', 't'] });
-      index.patch('put', entry).orThrow();
-      expect(ids(index.byTag('dup' as Tag))).toEqual(['a']);
-      expect(targetIds(index.backlinks(bt('t')))).toEqual(['a']);
-      index.patch('delete', entry).orThrow();
-      expect(index.byTag('dup' as Tag)).toHaveLength(0);
-      expect(index.backlinks(bt('t'))).toHaveLength(0);
-    });
-  });
-});