@fgv/ts-agent-memory 5.1.0-45 → 5.1.0-46

package/src/test/unit/types/writePolicy.test.ts

@@ -149,6 +149,68 @@ describe('KnowledgeLwwPolicy', () => {
       );
     });
   });
+
+  /**
+   * Pins the provenance merge contract documented in the package README
+   * (§ "Record updates — the merge contract"). `provenance` is on this policy's
+   * PINNED mutable surface, so these four behaviors are guarantees a consumer
+   * may depend on — not incidental consequences of the merge configuration. If
+   * one of these ever changes, the README claim is wrong and must move with it.
+   */
+  describe('provenance merge contract (README-pinned)', () => {
+    /** `provenance` with one key to clear, one to revise, and one to leave alone. */
+    function provenanceRecord(): IMemoryRecord<unknown> {
+      return makeRecord({
+        provenance: { source: 'agent', confidence: 0.9, note: 'stale' } as IProvenance
+      });
+    }
+
+    test('an explicit null on a sub-key clears that key and preserves its siblings', () => {
+      expect(policy.applyUpdate(provenanceRecord(), { provenance: { note: null } })).toSucceedAndSatisfy(
+        (updated) => {
+          expect(updated.envelope.provenance).toEqual({ source: 'agent', confidence: 0.9 });
+        }
+      );
+    });
+
+    test('a sub-key revision merges per key and preserves untouched siblings', () => {
+      expect(policy.applyUpdate(provenanceRecord(), { provenance: { confidence: 0.5 } })).toSucceedAndSatisfy(
+        (updated) => {
+          expect(updated.envelope.provenance).toEqual({
+            source: 'agent',
+            confidence: 0.5,
+            note: 'stale'
+          });
+        }
+      );
+    });
+
+    test('a whole-block null is rejected loudly rather than silently accepted', () => {
+      expect(policy.applyUpdate(provenanceRecord(), { provenance: null })).toFailWith(
+        /may not delete required field\(s\): provenance/i
+      );
+    });
+
+    test('a patch that does not mention provenance leaves it untouched', () => {
+      expect(policy.applyUpdate(provenanceRecord(), { tags: ['x'] })).toSucceedAndSatisfy((updated) => {
+        expect(updated.envelope.provenance).toEqual({
+          source: 'agent',
+          confidence: 0.9,
+          note: 'stale'
+        });
+      });
+    });
+
+    test('the existing record is not mutated in place', () => {
+      const existing = provenanceRecord();
+      expect(policy.applyUpdate(existing, { provenance: { note: null } })).toSucceed();
+      expect(existing.envelope.provenance).toEqual({
+        source: 'agent',
+        confidence: 0.9,
+        note: 'stale'
+      });
+    });
+  });
 });
 
 describe('MemoryCapCullPolicy', () => {
@@ -330,5 +392,55 @@ describe('MemoryCapCullPolicy', () => {
         expect(updated.envelope.embeddingRef).toBe('vec-keep');
       });
     });
+
+    /**
+     * Pins the policy-dependence caveat the README states alongside the
+     * provenance merge contract: unlike {@link KnowledgeLwwPolicy}'s pinned
+     * surface, this policy's surface is caller-supplied, so a consumer who does
+     * not declare `provenance` mutable gets NEITHER the sub-key clear NOR the
+     * loud whole-block rejection — every provenance patch key is simply inert.
+     */
+    describe('provenance guarantees are policy-dependent (README-pinned)', () => {
+      const bodyOnly = (): MemoryCapCullPolicy =>
+        MemoryCapCullPolicy.create({ maxRecords: 5, mutableFields: ['body'] }).orThrow();
+
+      function undeclaredProvenanceRecord(): IMemoryRecord<unknown> {
+        return makeRecord(
+          {
+            id: 'turn-0' as MemoryId,
+            kind: 'summarized-turn' as Kind,
+            provenance: { source: 'agent', note: 'stale' } as IProvenance
+          },
+          { summary: 'old' }
+        );
+      }
+
+      test('a sub-key null is inert when provenance is not declared mutable', () => {
+        expect(
+          bodyOnly().applyUpdate(undeclaredProvenanceRecord(), { provenance: { note: null } })
+        ).toSucceedAndSatisfy((updated) => {
+          expect(updated.envelope.provenance).toEqual({ source: 'agent', note: 'stale' });
+        });
+      });
+
+      test('a whole-block null is a silent no-op, not an error, when provenance is not declared mutable', () => {
+        expect(
+          bodyOnly().applyUpdate(undeclaredProvenanceRecord(), { provenance: null })
+        ).toSucceedAndSatisfy((updated) => {
+          expect(updated.envelope.provenance).toEqual({ source: 'agent', note: 'stale' });
+        });
+      });
+
+      test('declaring provenance mutable restores both guarantees', () => {
+        expect(
+          policy.applyUpdate(undeclaredProvenanceRecord(), { provenance: { note: null } })
+        ).toSucceedAndSatisfy((updated) => {
+          expect(updated.envelope.provenance).toEqual({ source: 'agent' });
+        });
+        expect(policy.applyUpdate(undeclaredProvenanceRecord(), { provenance: null })).toFailWith(
+          /may not delete required field\(s\): provenance/i
+        );
+      });
+    });
   });
 });

package/src/test/unit/vector/fragmentConverters.test.ts

@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import '@fgv/ts-utils-jest';
+import { IEmbeddedFragment, embeddedFragmentConverter, fragmentLocatorConverter } from '../../../index';
+
+describe('fragmentLocatorConverter', () => {
+  test('converts a well-formed span', () => {
+    expect(fragmentLocatorConverter.convert({ start: 3, end: 11 })).toSucceedWith({ start: 3, end: 11 });
+  });
+
+  test('rejects a non-numeric offset', () => {
+    expect(fragmentLocatorConverter.convert({ start: 'nope', end: 11 })).toFailWith(/start/i);
+  });
+
+  test('rejects a span missing an offset', () => {
+    expect(fragmentLocatorConverter.convert({ start: 3 })).toFailWith(/end/i);
+  });
+});
+
+describe('embeddedFragmentConverter', () => {
+  const vector: Float32Array = Float32Array.from([1, 0, 0]);
+
+  describe('identity invariant', () => {
+    test('accepts a fragment identified only by its locator', () => {
+      expect(
+        embeddedFragmentConverter.convert({ locator: { start: 0, end: 4 }, vector })
+      ).toSucceedAndSatisfy((fragment: IEmbeddedFragment) => {
+        expect(fragment.locator).toEqual({ start: 0, end: 4 });
+        expect(fragment.fragmentId).toBeUndefined();
+      });
+    });
+
+    test('accepts a fragment identified only by its fragmentId', () => {
+      expect(embeddedFragmentConverter.convert({ fragmentId: 'frag-7', vector })).toSucceedAndSatisfy(
+        (fragment: IEmbeddedFragment) => {
+          expect(fragment.fragmentId).toBe('frag-7');
+          expect(fragment.locator).toBeUndefined();
+        }
+      );
+    });
+
+    test('accepts a fragment carrying both identities', () => {
+      expect(
+        embeddedFragmentConverter.convert({ locator: { start: 0, end: 4 }, fragmentId: 'frag-7', vector })
+      ).toSucceedAndSatisfy((fragment: IEmbeddedFragment) => {
+        expect(fragment.locator).toEqual({ start: 0, end: 4 });
+        expect(fragment.fragmentId).toBe('frag-7');
+      });
+    });
+
+    test('rejects a fragment carrying neither identity', () => {
+      expect(embeddedFragmentConverter.convert({ vector })).toFailWith(
+        /at least one of .locator. or .fragmentId./i
+      );
+    });
+  });
+
+  describe('field validation', () => {
+    test('rejects a vector that is not a Float32Array', () => {
+      expect(embeddedFragmentConverter.convert({ fragmentId: 'frag-7', vector: [1, 0, 0] })).toFailWith(
+        /Float32Array/i
+      );
+    });
+
+    test('rejects a missing vector', () => {
+      expect(embeddedFragmentConverter.convert({ fragmentId: 'frag-7' })).toFailWith(/vector/i);
+    });
+
+    test('rejects a non-string fragmentId', () => {
+      expect(embeddedFragmentConverter.convert({ fragmentId: 7, vector })).toFailWith(/fragmentId/i);
+    });
+
+    test('rejects a malformed locator', () => {
+      expect(embeddedFragmentConverter.convert({ locator: { start: 0 }, vector })).toFailWith(/locator/i);
+    });
+  });
+});

package/src/test/unit/vector/inMemoryFragmentCosineIndex.test.ts

@@ -386,4 +386,92 @@ describe('InMemoryFragmentCosineIndex', () => {
       expect(index.recordCount).toBe(0);
     });
   });
+
+  describe('fragment identity', () => {
+    /** A fragment identified only by an opaque id — no honest body span. */
+    function idFrag(fragmentId: string, vector: number[]): IEmbeddedFragment {
+      return { fragmentId, vector: Float32Array.from(vector) };
+    }
+
+    test('rejects a fragment carrying neither a locator nor a fragmentId', async () => {
+      const index = InMemoryFragmentCosineIndex.create().orThrow();
+      expect(
+        await index.addFragments(target('knowledge', 'doc-a'), [{ vector: Float32Array.from([1, 0]) }])
+      ).toFailWith(/at least one of 'locator' or 'fragmentId'/i);
+      expect(index.recordCount).toBe(0);
+    });
+
+    test('carries an opaque fragmentId through to the query hit verbatim', async () => {
+      const index = InMemoryFragmentCosineIndex.create().orThrow();
+      const opaque = 'urn:frag:9f8e::{not-parsed}';
+      (await index.addFragments(target('knowledge', 'doc-a'), [idFrag(opaque, [1, 0])])).orThrow();
+      expect(await index.query(Float32Array.from([1, 0]), 1)).toSucceedAndSatisfy(
+        (hits: ReadonlyArray<IVectorQueryHit>) => {
+          expect(hits[0].fragmentId).toBe(opaque);
+          expect(hits[0].locator).toBeUndefined();
+        }
+      );
+    });
+
+    test('carries both identities when a fragment supplies both', async () => {
+      const index = InMemoryFragmentCosineIndex.create().orThrow();
+      (
+        await index.addFragments(target('knowledge', 'doc-a'), [
+          { ...frag(2, 8, [1, 0]), fragmentId: 'frag-1' }
+        ])
+      ).orThrow();
+      expect(await index.query(Float32Array.from([1, 0]), 1)).toSucceedAndSatisfy(
+        (hits: ReadonlyArray<IVectorQueryHit>) => {
+          expect(hits[0].locator).toEqual(loc(2, 8));
+          expect(hits[0].fragmentId).toBe('frag-1');
+        }
+      );
+    });
+
+    test('a locator-only fragment produces a hit with no fragmentId key at all', async () => {
+      // Byte-identical to what the index produced before `fragmentId` existed: the key
+      // is absent, not present-and-undefined, so an existing caller's structural
+      // comparisons are unaffected by the addition.
+      const index = InMemoryFragmentCosineIndex.create().orThrow();
+      (await index.addFragments(target('knowledge', 'doc-a'), [frag(0, 5, [1, 0])])).orThrow();
+      expect(await index.query(Float32Array.from([1, 0]), 1)).toSucceedAndSatisfy(
+        (hits: ReadonlyArray<IVectorQueryHit>) => {
+          expect(Object.keys(hits[0]).sort()).toEqual(['locator', 'score', 'target']);
+          expect(hits[0]).toStrictEqual({
+            target: target('knowledge', 'doc-a'),
+            score: hits[0].score,
+            locator: loc(0, 5)
+          });
+        }
+      );
+    });
+
+    test('an id-only fragment produces a hit with no locator key at all', async () => {
+      const index = InMemoryFragmentCosineIndex.create().orThrow();
+      (await index.addFragments(target('knowledge', 'doc-a'), [idFrag('frag-1', [1, 0])])).orThrow();
+      expect(await index.query(Float32Array.from([1, 0]), 1)).toSucceedAndSatisfy(
+        (hits: ReadonlyArray<IVectorQueryHit>) => {
+          expect(Object.keys(hits[0]).sort()).toEqual(['fragmentId', 'score', 'target']);
+        }
+      );
+    });
+
+    test('mixes identity shapes within one record and within one query', async () => {
+      const index = InMemoryFragmentCosineIndex.create().orThrow();
+      (
+        await index.addFragments(target('knowledge', 'doc-a'), [
+          frag(0, 5, [1, 0]),
+          idFrag('frag-rewritten', [0, 1])
+        ])
+      ).orThrow();
+      expect(await index.query(Float32Array.from([1, 0]), 2)).toSucceedAndSatisfy(
+        (hits: ReadonlyArray<IVectorQueryHit>) => {
+          expect(hits[0].locator).toEqual(loc(0, 5));
+          expect(hits[0].fragmentId).toBeUndefined();
+          expect(hits[1].fragmentId).toBe('frag-rewritten');
+          expect(hits[1].locator).toBeUndefined();
+        }
+      );
+    });
+  });
 });

package/temp/build/lint/_eslint-5eVG3S6w.json

@@ -23,7 +23,7 @@
     ],
     [
       "packlets/types/writePolicy.ts",
-      "0b914ac826cd126c34f73156a8b98efbbab44ef86dc476342a5d1c0afba485e6_5FxNr7n+qjkV58wA2j2YZUqKABE="
+      "239707437000bfeaaa44dd6ca0f6a582a55dc149a567ceedec2b9be42b8f6f46_5FxNr7n+qjkV58wA2j2YZUqKABE="
     ],
     [
       "packlets/types/index.ts",
@@ -63,7 +63,11 @@
     ],
     [
       "packlets/vector/vectorIndex.ts",
-      "1c38168a3ec3af3c721c3baeec92d3a26b83fc5027125bf538a44624bd2f4bb3_5FxNr7n+qjkV58wA2j2YZUqKABE="
+      "fa4879a08b8cb1631f6a8e968d0df8fb803a0a33db6265cd03f5e566de8f0f82_5FxNr7n+qjkV58wA2j2YZUqKABE="
+    ],
+    [
+      "packlets/vector/fragmentConverters.ts",
+      "7253c019d02c288dec21314579f63d40af7db6fb08fe9f4af09cfb6a8cdb71f6_5FxNr7n+qjkV58wA2j2YZUqKABE="
     ],
     [
       "packlets/vector/inMemoryCosineIndex.ts",
@@ -71,11 +75,11 @@
     ],
     [
       "packlets/vector/inMemoryFragmentCosineIndex.ts",
-      "e36e5909e9b8670f6d7188fead24d0d05c2d54ef8594eaafb6d7cabd3137703c_5FxNr7n+qjkV58wA2j2YZUqKABE="
+      "8e2464ba6c1f87551b7588fadb5fc92cd1a5e4f5e5714171759073c8c1cc9b3b_5FxNr7n+qjkV58wA2j2YZUqKABE="
     ],
     [
       "packlets/vector/index.ts",
-      "79a792cf9507922def7bf2a3d981051b87157a3113509f7e59a3917cc21efaa6_5FxNr7n+qjkV58wA2j2YZUqKABE="
+      "8049e688c06aadd87e7ef453e0307662b49ba2f2c245d6ea59c6cabe3a53bc14_5FxNr7n+qjkV58wA2j2YZUqKABE="
     ],
     [
       "packlets/store/scopeEncoding.ts",
@@ -83,7 +87,7 @@
     ],
     [
       "packlets/store/fileTreeMemoryStore.ts",
-      "b731f625651dec82aa9f10196e0855152f7d8ef42b45830a7ef866d9384cf57e_5FxNr7n+qjkV58wA2j2YZUqKABE="
+      "fb5d920197b7c3d292dde8690151ee9e125826af9df88cc4c897fc1b4dbd6032_5FxNr7n+qjkV58wA2j2YZUqKABE="
     ],
     [
       "packlets/store/index.ts",
@@ -115,7 +119,7 @@
     ],
     [
       "packlets/retrieve/fragmentSemanticRetriever.ts",
-      "2308f9c8582ba9c787151e63409a72dc01f408837897bb669339780c15f08500_5FxNr7n+qjkV58wA2j2YZUqKABE="
+      "06a4d99730c38e8430f3aaf5472530d54110cd17f48d57585b7d6ea5548157eb_5FxNr7n+qjkV58wA2j2YZUqKABE="
     ],
     [
       "packlets/retrieve/temporalRetrievers.ts",
@@ -219,12 +223,16 @@
     ],
     [
       "test/unit/store/fileTreeMemoryStore.test.ts",
-      "06407be1a2dc1b914cecefe63766ea4a597c132cc04e87d8b2a373d582be435f_fnTnCS8rja7DE6jB0bKRna1pZAg="
+      "7ab5f3104461c232d0c37c7f8519a1dbb7a75df0f6f186fd324846321ca146ff_fnTnCS8rja7DE6jB0bKRna1pZAg="
     ],
     [
       "test/unit/store/fragmentEmbedOnWrite.test.ts",
       "70969bc20e808fc082eaad736072e783314b6d245c12f9db2d69caf942588a8b_fnTnCS8rja7DE6jB0bKRna1pZAg="
     ],
+    [
+      "test/unit/store/indexInjection.test.ts",
+      "b521f5197e59f488e39a7620c53088776a69f7c31cf3b451bb9f089230e83ec9_fnTnCS8rja7DE6jB0bKRna1pZAg="
+    ],
     [
       "test/unit/store/lenientOpen.test.ts",
       "f7051e2e38e4a195585e3fa4e36c373f909032141da7f77043bbd8d0a9808d75_fnTnCS8rja7DE6jB0bKRna1pZAg="
@@ -267,11 +275,15 @@
     ],
     [
       "test/unit/types/temporalPolicy.test.ts",
-      "f6ff83abe5e9e418ee0445f54eda869f1400d49cd11529da9be06c69be7f7c70_fnTnCS8rja7DE6jB0bKRna1pZAg="
+      "5f757ea55ba1e2fc3a9e5ec3027a03a186f69cb8388dc2cd57241ecd9ac453f3_fnTnCS8rja7DE6jB0bKRna1pZAg="
     ],
     [
       "test/unit/types/writePolicy.test.ts",
-      "f36d20bf300ab0ebe8921e5125be6dcfd1fd1a39d51bff1e7f301f1c60661c98_fnTnCS8rja7DE6jB0bKRna1pZAg="
+      "55d66cedb5ee43e0692df8351f4c19039d32c71fb24ba7ce803d8657f27b95b5_fnTnCS8rja7DE6jB0bKRna1pZAg="
+    ],
+    [
+      "test/unit/vector/fragmentConverters.test.ts",
+      "2871bb0b9ba94d131c4b34464de85627ecf54cbb71319037b88132c05b2eb594_fnTnCS8rja7DE6jB0bKRna1pZAg="
     ],
     [
       "test/unit/vector/inMemoryCosineIndex.test.ts",
@@ -279,12 +291,12 @@
     ],
     [
       "test/unit/vector/inMemoryFragmentCosineIndex.test.ts",
-      "31c89a1306fda1a18617af5c2c3419cba1623be7c25a01d66eb70fb60d3ee3c2_fnTnCS8rja7DE6jB0bKRna1pZAg="
+      "bd4b7312b74ab15ae7ca45c8c8701a984fddbd668364329912fefdf7ee54fe89_fnTnCS8rja7DE6jB0bKRna1pZAg="
     ],
     [
       "test/unit/vector/vectorIndex.test.ts",
       "ee46f9a64127b829fea5ce21e63481d2ad757cfc9d04b389bd27e146b6a0c136_fnTnCS8rja7DE6jB0bKRna1pZAg="
     ]
   ],
-  "filesHash": "j1KLdy1WJzKu5I98SSDO1g"
+  "filesHash": "X7iKqGCJheFY-yEDd2SfZw"
 }