@fgv/ts-agent-memory 5.1.0-36

package/src/packlets/vector/vectorIndex.ts

@@ -0,0 +1,78 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Result } from '@fgv/ts-utils';
+import { IMemoryRecord, MemoryId } from '../types';
+
+/**
+ * A single hit returned by {@link IVectorIndex.query}: the matched record id and
+ * the backend's similarity score (higher = more similar; the exact scale is
+ * backend-defined). Hits are returned in descending score order.
+ * @public
+ */
+export interface IVectorQueryHit {
+  /** The id of the matched record. */
+  readonly id: MemoryId;
+  /** Backend similarity score; higher is more similar. */
+  readonly score: number;
+}
+
+/**
+ * The vector-index seam an embedding backend implements to make
+ * {@link SemanticRetriever | semantic recall} operational.
+ *
+ * @remarks
+ * Vectors cross this seam as `Float32Array` (the in-memory representation an
+ * embedding model produces); `number[]` is reserved for the JSON-wire edges
+ * (e.g. a provider's embedding response). The in-package brute-force cosine
+ * implementation is {@link InMemoryCosineIndex}; a consumer can swap an external
+ * ANN backend behind the same seam once N grows beyond the in-memory regime.
+ *
+ * Every operation returns a `Result` (async, since a real backend does I/O) so
+ * failure is explicit and never throws across the seam.
+ * @public
+ */
+export interface IVectorIndex {
+  /**
+   * Add (or replace) the embedding for `id`. Returns the opaque
+   * {@link IMemoryEnvelope.embeddingRef | embeddingRef} the store stamps onto
+   * the envelope so a later read knows the record is embedded.
+   */
+  add(id: MemoryId, vector: Float32Array): Promise<Result<string>>;
+
+  /**
+   * Remove the embedding for `id`. Returns the removed id. Idempotent — removing
+   * an id with no embedding still succeeds (returns the id).
+   */
+  remove(id: MemoryId): Promise<Result<MemoryId>>;
+
+  /**
+   * Return the `topK` nearest records to `vector`, in descending score order.
+   */
+  query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+}
+
+/**
+ * Embeds a complete record into a vector for the store's embed-on-write hook.
+ * Async and `Result`-returning, since a real embedder does a network call (cloud
+ * provider) or in-process model inference. The consumer wires this — the core
+ * package never calls an embedding provider directly, staying embedder-agnostic.
+ * @public
+ */
+export type MemoryEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<Float32Array>>;
+
+/**
+ * The minimal record-source surface {@link InMemoryCosineIndex.rebuild} reads to
+ * re-embed an entire vault. {@link IMemoryStore} satisfies it structurally (its
+ * `list` accepts an optional filter, which is assignable to this no-argument
+ * shape), so a consumer passes the store directly — without the vector packlet
+ * taking a dependency on the store packlet (which depends on the vector packlet
+ * for {@link IVectorIndex}, so the reverse import would be a cycle).
+ * @public
+ */
+export interface IMemoryRecordSource {
+  /** List every record in the vault. */
+  list(): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+}

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

@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import '@fgv/ts-utils-jest';
+import { Converters } from '@fgv/ts-utils';
+import { JsonSchema } from '@fgv/ts-json-base';
+import { BodyConverterRegistry } from '../../../packlets/converters';
+import { Kind } from '../../../packlets/types';
+
+const knowledgeKind: Kind = 'knowledge' as Kind;
+const profileKind: Kind = 'profile' as Kind;
+
+describe('BodyConverterRegistry', () => {
+  let registry: BodyConverterRegistry;
+
+  beforeEach(() => {
+    registry = BodyConverterRegistry.create().orThrow();
+  });
+
+  test('create succeeds', () => {
+    expect(BodyConverterRegistry.create()).toSucceed();
+  });
+
+  describe('register / has / convert', () => {
+    test('registers a Converter and converts a matching body', () => {
+      registry.register(knowledgeKind, Converters.string);
+      expect(registry.has(knowledgeKind)).toBe(true);
+      expect(registry.convert(knowledgeKind, 'a knowledge doc')).toSucceedWith('a knowledge doc');
+    });
+
+    test('a registered Converter rejects an invalid body', () => {
+      registry.register(knowledgeKind, Converters.string);
+      expect(registry.convert(knowledgeKind, 42)).toFail();
+    });
+
+    test('has returns false for an unregistered kind', () => {
+      expect(registry.has(knowledgeKind)).toBe(false);
+    });
+
+    test('convert fails for an unregistered kind', () => {
+      expect(registry.convert(knowledgeKind, 'x')).toFailWith(
+        /no converter registered for kind 'knowledge'/i
+      );
+    });
+
+    test('register replaces a prior registration for the same kind', () => {
+      registry.register(knowledgeKind, Converters.string);
+      registry.register(knowledgeKind, Converters.number);
+      expect(registry.convert(knowledgeKind, 7)).toSucceedWith(7);
+      expect(registry.convert(knowledgeKind, 'x')).toFail();
+    });
+  });
+
+  describe('getConverter', () => {
+    test('returns the registered converter', () => {
+      registry.register(knowledgeKind, Converters.string);
+      expect(registry.getConverter(knowledgeKind)).toSucceedAndSatisfy((converter) => {
+        expect(converter.convert('hello')).toSucceedWith('hello');
+      });
+    });
+
+    test('fails for an unregistered kind', () => {
+      expect(registry.getConverter(knowledgeKind)).toFailWith(/no converter registered for kind/i);
+    });
+  });
+
+  describe('registerSchema', () => {
+    const profileSchema = JsonSchema.object({
+      name: JsonSchema.string(),
+      age: JsonSchema.integer()
+    });
+
+    test('registers a JsonSchema validator and validates a matching body', () => {
+      registry.registerSchema(profileKind, profileSchema);
+      expect(registry.has(profileKind)).toBe(true);
+      expect(registry.convert(profileKind, { name: 'Ada', age: 36 })).toSucceedWith({
+        name: 'Ada',
+        age: 36
+      });
+    });
+
+    test('a registered schema rejects an invalid body', () => {
+      registry.registerSchema(profileKind, profileSchema);
+      expect(registry.convert(profileKind, { name: 'Ada' })).toFail();
+    });
+  });
+});

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

@@ -0,0 +1,261 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import '@fgv/ts-utils-jest';
+import { Converters } from '@fgv/ts-utils';
+import {
+  BodyConverterRegistry,
+  edgeConverter,
+  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: '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('fails when source is missing', () => {
+    expect(provenanceConverter.convert({ by: 'erik' })).toFail();
+  });
+
+  test('fails on a non-object', () => {
+    expect(provenanceConverter.convert('nope')).toFail();
+  });
+});
+
+describe('edgeConverter', () => {
+  test('validates a full attributed edge', () => {
+    expect(
+      edgeConverter.convert({
+        type: 'mtm-ref',
+        target: '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).toBe('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: 'ownership' })).toSucceedAndSatisfy((edge) => {
+      expect(edge.type).toBe('related');
+      expect(edge.target).toBe('ownership');
+      expect(edge.confidence).toBeUndefined();
+    });
+  });
+
+  test('accepts a null invalid_at (still valid)', () => {
+    expect(edgeConverter.convert({ type: 'related', target: '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: 'x', invalid_at: 'soon' })).toFail();
+  });
+
+  test('fails when target is missing', () => {
+    expect(edgeConverter.convert({ type: 'related' })).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('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('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

@@ -0,0 +1,187 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import '@fgv/ts-utils-jest';
+import {
+  IIndexedMemoryRecord,
+  IMemoryRecord,
+  Kind,
+  MemoryId,
+  MemoryIndex,
+  MemoryScopeKey,
+  Tag,
+  envelopeConverter
+} from '../../../index';
+
+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;
+}
+
+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 })),
+        created: 0,
+        updated: spec.updated ?? 0,
+        seq: spec.seq ?? 0,
+        contentHash: 'h',
+        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('none' as MemoryId)).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(index.backlinks('b' as MemoryId)).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(index.backlinks('b' as MemoryId)).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('b' as MemoryId)).toHaveLength(0);
+      expect(index.backlinks('c' as MemoryId)).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('b' as MemoryId)).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('backlinks', () => {
+    test('aggregates multiple sources pointing at one target', () => {
+      index
+        .rebuild([makeEntry({ id: 'a', links: ['target'] }), makeEntry({ id: 'b', links: ['target'] })])
+        .orThrow();
+      expect([...index.backlinks('target' as MemoryId)].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('target' as MemoryId)).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(index.backlinks('target' as MemoryId)).toEqual(['a', 'a']);
+      index.patch('delete', a1).orThrow();
+      expect(index.backlinks('target' as MemoryId)).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(index.backlinks('t' as MemoryId)).toEqual(['a']);
+      index.patch('delete', entry).orThrow();
+      expect(index.byTag('dup' as Tag)).toHaveLength(0);
+      expect(index.backlinks('t' as MemoryId)).toHaveLength(0);
+    });
+  });
+});