@fgv/ts-agent-memory 5.1.0-39 → 5.1.0-41

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

@@ -46,7 +46,7 @@ describe('antagonist — full on-disk round-trip preserves every optional field'
       links: [
         {
           type: 'rel' as never,
-          target: 'doc-2' as never,
+          target: { scope: 'knowledge', id: 'doc-2' } as never,
           confidence: 0.42,
           provenance: { source: 'agent', by: 'curator', extra: { nested: true } },
           valid_at: 111,
@@ -63,7 +63,7 @@ describe('antagonist — full on-disk round-trip preserves every optional field'
         by: 'erik',
         model: 'gpt-5',
         confidence: 0.87,
-        derivedFrom: 'turn-3' as never,
+        derivedFrom: { scope: 'conversations/c1', id: 'turn-3' } as never,
         // Opaque extension keys (per IProvenance's `[key: string]: unknown` arm).
         sentiment: { score: 0.5 },
         epistemic: 'belief'
@@ -89,7 +89,7 @@ describe('antagonist — full on-disk round-trip preserves every optional field'
       entityId: 'doc-2' as IMemoryEnvelope['entityId'],
       kind,
       tags: [],
-      links: [{ type: 'rel' as never, target: 'doc-3' as never }],
+      links: [{ type: 'rel' as never, target: { scope: 'knowledge', id: 'doc-3' } as never }],
       created: 0,
       updated: 0,
       seq: 0,

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

@@ -8,6 +8,7 @@ import { Converters } from '@fgv/ts-utils';
 import {
   BodyConverterRegistry,
   edgeConverter,
+  edgeTargetConverter,
   envelopeConverter,
   envelopeYamlConverter,
   joinFrontmatter,
@@ -24,7 +25,7 @@ const validEnvelopeObject: Record<string, unknown> = {
   entityId: 'intro-to-rust',
   kind: 'knowledge',
   tags: ['rust', 'systems'],
-  links: [{ type: 'related', target: 'ownership' }],
+  links: [{ type: 'related', target: { scope: 'knowledge', id: 'ownership' } }],
   created: 1000,
   updated: 2000,
   seq: 5,
@@ -53,6 +54,33 @@ describe('provenanceConverter', () => {
     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();
   });
@@ -62,12 +90,34 @@ describe('provenanceConverter', () => {
   });
 });
 
+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: 'turn-3',
+        target: { scope: 'conversations/conv-a', id: 'turn-3' },
         confidence: 0.8,
         provenance: { source: 'agent' },
         valid_at: 100,
@@ -75,7 +125,7 @@ describe('edgeConverter', () => {
       })
     ).toSucceedAndSatisfy((edge) => {
       expect(edge.type).toBe('mtm-ref');
-      expect(edge.target).toBe('turn-3');
+      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);
@@ -84,28 +134,36 @@ describe('edgeConverter', () => {
   });
 
   test('validates a minimal edge', () => {
-    expect(edgeConverter.convert({ type: 'related', target: 'ownership' })).toSucceedAndSatisfy((edge) => {
+    expect(
+      edgeConverter.convert({ type: 'related', target: { scope: 'knowledge', id: 'ownership' } })
+    ).toSucceedAndSatisfy((edge) => {
       expect(edge.type).toBe('related');
-      expect(edge.target).toBe('ownership');
+      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: 'x', invalid_at: null })).toSucceedAndSatisfy(
-      (edge) => {
-        expect(edge.invalid_at).toBeNull();
-      }
-    );
+    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: 'x', invalid_at: 'soon' })).toFail();
+    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', () => {
@@ -157,6 +215,34 @@ describe('envelopeConverter', () => {
     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;
@@ -239,6 +325,77 @@ describe('parseMemoryFile / serializeMemoryFile', () => {
     });
   });
 
+  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);
   });

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

@@ -5,6 +5,7 @@
 
 import '@fgv/ts-utils-jest';
 import {
+  IEdgeTarget,
   IIndexedMemoryRecord,
   IMemoryRecord,
   Kind,
@@ -12,9 +13,27 @@ import {
   MemoryIndex,
   MemoryScopeKey,
   Tag,
-  envelopeConverter
+  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;
@@ -23,6 +42,7 @@ interface IRecordSpec {
   readonly links?: ReadonlyArray<string>;
   readonly updated?: number;
   readonly seq?: number;
+  readonly rank?: number;
 }
 
 function makeEntry(spec: IRecordSpec): IIndexedMemoryRecord {
@@ -33,11 +53,15 @@ function makeEntry(spec: IRecordSpec): IIndexedMemoryRecord {
         entityId: spec.id,
         kind: spec.kind ?? 'knowledge',
         tags: spec.tags ?? [],
-        links: (spec.links ?? []).map((target) => ({ type: 'rel', target })),
+        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(),
@@ -63,7 +87,7 @@ describe('MemoryIndex', () => {
       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);
+      expect(index.backlinks(bt('none'))).toHaveLength(0);
     });
   });
 
@@ -78,7 +102,7 @@ describe('MemoryIndex', () => {
       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']);
+      expect(targetIds(index.backlinks(bt('b')))).toEqual(['a']);
     });
 
     test('clears prior state', () => {
@@ -94,7 +118,7 @@ describe('MemoryIndex', () => {
       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']);
+      expect(targetIds(index.backlinks(bt('b')))).toEqual(['a']);
     });
 
     test('put on an existing key replaces stale associations', () => {
@@ -105,8 +129,8 @@ describe('MemoryIndex', () => {
       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']);
+      expect(index.backlinks(bt('b'))).toHaveLength(0);
+      expect(targetIds(index.backlinks(bt('c')))).toEqual(['a']);
     });
 
     test('delete removes the entry and its associations', () => {
@@ -115,7 +139,7 @@ describe('MemoryIndex', () => {
       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);
+      expect(index.backlinks(bt('b'))).toHaveLength(0);
     });
 
     test('delete of an absent key is a no-op that still succeeds', () => {
@@ -145,19 +169,80 @@ describe('MemoryIndex', () => {
     });
   });
 
+  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([...index.backlinks('target' as MemoryId)].sort()).toEqual(['a', 'b']);
+      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('target' as MemoryId)).toHaveLength(0);
+      expect(index.backlinks(bt('target'))).toHaveLength(0);
     });
 
     test('tracks same-id sources across scopes independently', () => {
@@ -167,9 +252,9 @@ describe('MemoryIndex', () => {
       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']);
+      expect(targetIds(index.backlinks(bt('target')))).toEqual(['a', 'a']);
       index.patch('delete', a1).orThrow();
-      expect(index.backlinks('target' as MemoryId)).toEqual(['a']);
+      expect(targetIds(index.backlinks(bt('target')))).toEqual(['a']);
     });
   });
 
@@ -178,10 +263,10 @@ describe('MemoryIndex', () => {
       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']);
+      expect(targetIds(index.backlinks(bt('t')))).toEqual(['a']);
       index.patch('delete', entry).orThrow();
       expect(index.byTag('dup' as Tag)).toHaveLength(0);
-      expect(index.backlinks('t' as MemoryId)).toHaveLength(0);
+      expect(index.backlinks(bt('t'))).toHaveLength(0);
     });
   });
 });

package/src/test/unit/ingest/antagonistCycleAndParity.test.ts

@@ -21,6 +21,7 @@ import {
   IBodyConverterRegistry,
   ICandidateEdge,
   ICandidateRecord,
+  IEdgeTarget,
   IEntityResolutionCandidate,
   IEntityResolver,
   IFactExtractor,
@@ -38,12 +39,18 @@ import {
   KnowledgeIdentityCodec,
   MemoryId,
   MemoryIngestOrchestrator,
+  MemoryScopeKey,
   ResolutionVerdict,
   Tag
 } from '../../../index';
 
 const noteKind: Kind = 'note' as Kind;
 
+/** A scope-qualified target for the note fixtures (all under the knowledge scope). */
+function kt(id: string): IEdgeTarget {
+  return { scope: 'knowledge' as MemoryScopeKey, id: id as MemoryId };
+}
+
 function mutableRoot(): FileTree.IMutableFileTreeDirectoryItem {
   const tree = FileTree.inMemory([], { mutable: true }).orThrow();
   const root = tree.getDirectory('/').orThrow();
@@ -131,7 +138,7 @@ function candidate(
 }
 
 function candEdge(source: string, type: string, target: string): ICandidateEdge {
-  return { source: source as MemoryId, edge: { type: type as never, target: target as MemoryId } };
+  return { source: kt(source), edge: { type: type as never, target: kt(target) } };
 }
 
 function buildOrchestrator(params: {
@@ -159,7 +166,7 @@ describe('antagonist — cycle guard through EXISTING store edges (integration)'
   test('a proposed edge that closes a cycle through a pre-existing on-disk edge is rejected', async () => {
     const store = buildStore();
     // Existing on-disk edge: doc-a -> doc-b (persisted before this ingest runs).
-    await putFull(store, 'doc-a', 'anchor-a', [{ type: 'rel' as never, target: 'doc-b' as MemoryId }]);
+    await putFull(store, 'doc-a', 'anchor-a', [{ type: 'rel' as never, target: kt('doc-b') }]);
     await putFull(store, 'doc-b', 'anchor-b');
 
     // This ingest re-writes doc-b (a 'new'-verdict same-id update, since no
@@ -183,9 +190,9 @@ describe('antagonist — cycle guard through EXISTING store edges (integration)'
     const store = buildStore();
     // Existing chain: a -> b -> c -> d (four pre-existing on-disk edges spanning
     // three hops), persisted before this ingest.
-    await putFull(store, 'chain-a', 'a', [{ type: 'rel' as never, target: 'chain-b' as MemoryId }]);
-    await putFull(store, 'chain-b', 'b', [{ type: 'rel' as never, target: 'chain-c' as MemoryId }]);
-    await putFull(store, 'chain-c', 'c', [{ type: 'rel' as never, target: 'chain-d' as MemoryId }]);
+    await putFull(store, 'chain-a', 'a', [{ type: 'rel' as never, target: kt('chain-b') }]);
+    await putFull(store, 'chain-b', 'b', [{ type: 'rel' as never, target: kt('chain-c') }]);
+    await putFull(store, 'chain-c', 'c', [{ type: 'rel' as never, target: kt('chain-d') }]);
     await putFull(store, 'chain-d', 'd');
 
     // Proposed: chain-d -> chain-a, closing the whole loop through the existing chain.
@@ -199,7 +206,7 @@ describe('antagonist — cycle guard through EXISTING store edges (integration)'
 
   test('cycleGuard "off" admits a cycle that closes through an existing edge', async () => {
     const store = buildStore();
-    await putFull(store, 'doc-a', 'anchor-a', [{ type: 'rel' as never, target: 'doc-b' as MemoryId }]);
+    await putFull(store, 'doc-a', 'anchor-a', [{ type: 'rel' as never, target: kt('doc-b') }]);
     await putFull(store, 'doc-b', 'anchor-b');
     const orch = MemoryIngestOrchestrator.create({
       store,
@@ -211,7 +218,7 @@ describe('antagonist — cycle guard through EXISTING store edges (integration)'
       cycleGuard: 'off'
     }).orThrow();
     expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r: IIngestItemResult) => {
-      expect(r.records[0].record?.envelope.links).toEqual([{ type: 'rel', target: 'doc-a' }]);
+      expect(r.records[0].record?.envelope.links).toEqual([{ type: 'rel', target: kt('doc-a') }]);
     });
   });
 });
@@ -236,7 +243,7 @@ describe('antagonist — resolver target need not be a surfaced `similar` candid
         Promise.resolve(succeed(Float32Array.from([1, 0, 0])));
       // Only doc-a is embedded/indexed; doc-q is never surfaced by similarity —
       // it can only be reached by the resolver's own out-of-band choice.
-      (await vectorIndex.add('doc-a' as MemoryId, Float32Array.from([1, 0, 0]))).orThrow();
+      (await vectorIndex.add(kt('doc-a'), Float32Array.from([1, 0, 0]))).orThrow();
 
       const orch = MemoryIngestOrchestrator.create({
         store,
@@ -247,7 +254,7 @@ describe('antagonist — resolver target need not be a surfaced `similar` candid
         relationExtractor: relater(() => succeed([])),
         vectorIndex,
         embed,
-        entityResolver: resolver(() => succeed({ verdict, target: 'doc-q' as MemoryId } as ResolutionVerdict))
+        entityResolver: resolver(() => succeed({ verdict, target: kt('doc-q') } as ResolutionVerdict))
       }).orThrow();
 
       const result = await orch.ingestItem({ id: 'i', content: 'x' });
@@ -259,7 +266,7 @@ describe('antagonist — resolver target need not be a surfaced `similar` candid
       } else if (verdict === 'supersede') {
         expect(result).toSucceedAndSatisfy((r: IIngestItemResult) => {
           expect(r.records[0].disposition).toBe('written');
-          expect(r.records[0].resolution).toEqual({ verdict: 'supersede', target: 'doc-q' });
+          expect(r.records[0].resolution).toEqual({ verdict: 'supersede', target: kt('doc-q') });
         });
       } else {
         expect(result).toSucceedAndSatisfy((r: IIngestItemResult) => {
@@ -297,11 +304,11 @@ describe('antagonist — enum-branch parity: uniform structural rejection across
         relationExtractor: relater(() => succeed([])),
         vectorIndex,
         embed,
-        entityResolver: resolver(() => succeed({ verdict, target: 'ghost' as MemoryId } as ResolutionVerdict))
+        entityResolver: resolver(() => succeed({ verdict, target: kt('ghost') } as ResolutionVerdict))
       }).orThrow();
-      (await vectorIndex.add('doc-a' as MemoryId, Float32Array.from([1, 0, 0]))).orThrow();
+      (await vectorIndex.add(kt('doc-a'), Float32Array.from([1, 0, 0]))).orThrow();
       expect(await orch.ingestItem({ id: 'i', content: 'x' })).toFailWith(
-        `ingest 'i': ${verdict} target 'ghost' does not exist in the store`
+        `ingest 'i': ${verdict} target 'knowledge/ghost' does not exist in the store`
       );
     }
   );
@@ -349,13 +356,11 @@ describe('antagonist — enum-branch parity: uniform structural rejection across
         relationExtractor: relater(() => succeed([])),
         vectorIndex,
         embed,
-        entityResolver: resolver(() =>
-          succeed({ verdict, target: 'foreign-1' as MemoryId } as ResolutionVerdict)
-        )
+        entityResolver: resolver(() => succeed({ verdict, target: kt('foreign-1') } as ResolutionVerdict))
       }).orThrow();
-      (await vectorIndex.add('foreign-1' as MemoryId, Float32Array.from([1, 0, 0]))).orThrow();
+      (await vectorIndex.add(kt('foreign-1'), Float32Array.from([1, 0, 0]))).orThrow();
       expect(await orch.ingestItem({ id: 'i', content: 'x' })).toFailWith(
-        `ingest 'i': ${verdict} target 'foreign-1' is kind 'other' but the candidate is kind 'note'`
+        `ingest 'i': ${verdict} target 'knowledge/foreign-1' is kind 'other' but the candidate is kind 'note'`
       );
     }
   );