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

package/src/packlets/vector/vectorIndex.ts

@@ -7,10 +7,26 @@ import { Result } from '@fgv/ts-utils';
 import { IEdgeTarget, IMemoryRecord } from '../types';
 
 /**
- * A single hit returned by {@link IVectorIndex.query}: the matched record's
- * scope-qualified {@link IEdgeTarget | address} and the backend's similarity
- * score (higher = more similar; the exact scale is backend-defined). Hits are
- * returned in descending score order.
+ * A half-open `[start, end)` span into a record's body — the in-record locator a
+ * {@link IFragmentVectorIndex} carries on each fragment hit. `start` is inclusive,
+ * `end` exclusive. The unit (character / byte / token offsets) is the consumer's
+ * choice: the index stores the two integers opaquely and never interprets them,
+ * so they line up with whatever locator the consumer's own read side uses.
+ * @public
+ */
+export interface IFragmentLocator {
+  /** Inclusive start offset into the record body. */
+  readonly start: number;
+  /** Exclusive end offset into the record body. */
+  readonly end: number;
+}
+
+/**
+ * A single hit returned by {@link IVectorIndex.query} (or
+ * {@link IFragmentVectorIndex.query}): the matched record's scope-qualified
+ * {@link IEdgeTarget | address} and the backend's similarity score (higher = more
+ * similar; the exact scale is backend-defined). Hits are returned in descending
+ * score order.
  *
  * @remarks
  * The address is a `(scope, id)` pair, NOT a bare {@link MemoryId} — per-scope
@@ -18,6 +34,10 @@ import { IEdgeTarget, IMemoryRecord } from '../types';
  * stem under different scopes, so a bare id could not disambiguate two records
  * that share a stem. The caller re-resolves the hit against the record index by
  * the same scoped address.
+ *
+ * `locator` is present only on hits from a {@link IFragmentVectorIndex} — it
+ * identifies WHICH fragment of the record matched. Record-granular
+ * {@link IVectorIndex} hits omit it.
  * @public
  */
 export interface IVectorQueryHit {
@@ -25,6 +45,8 @@ export interface IVectorQueryHit {
   readonly target: IEdgeTarget;
   /** Backend similarity score; higher is more similar. */
   readonly score: number;
+  /** The matched fragment's in-record span; present only for fragment-index hits. */
+  readonly locator?: IFragmentLocator;
 }
 
 /**
@@ -65,6 +87,65 @@ export interface IVectorIndex {
   query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
 }
 
+/**
+ * One embedded fragment of a record: its in-record {@link IFragmentLocator | span}
+ * and the vector for that span. Produced by a {@link FragmentEmbedder} and stored
+ * via {@link IFragmentVectorIndex.addFragments}.
+ * @public
+ */
+export interface IEmbeddedFragment {
+  /** The fragment's in-record span. */
+  readonly locator: IFragmentLocator;
+  /** The embedding vector for that span. */
+  readonly vector: Float32Array;
+}
+
+/**
+ * The fragment-granular sibling of {@link IVectorIndex}: instead of one vector per
+ * record it holds many vectors per record, each tagged with an in-record
+ * {@link IFragmentLocator}, and its `query` returns per-fragment hits carrying that
+ * locator. This is the seam behind sub-document semantic search — the "discovery"
+ * half of a search-then-read contract, where a hit's `(target, locator)` tells the
+ * consumer which record AND which span to read.
+ *
+ * @remarks
+ * Deliberately NOT `extends IVectorIndex`: an index keyed by `(target, locator)`
+ * has no well-defined single-vector `add(target, vector)`. It is a parallel
+ * contract with three operations — `addFragments`, `remove`, `query` — reusing
+ * {@link IVectorQueryHit} (whose `locator` is always populated here). Kept distinct
+ * from the record-granular index per the consumer contract: memory recall stays
+ * record-granular; sub-document knowledge uses a separate fragment index.
+ * @public
+ */
+export interface IFragmentVectorIndex {
+  /**
+   * Add (or replace) all fragments for the scope-qualified `target`. Whole-record
+   * semantics: every fragment previously held for `target` is dropped and replaced
+   * by `fragments`, so a re-authored document never leaves stale fragments behind.
+   * Returns the number of fragments now held for the record.
+   */
+  addFragments(target: IEdgeTarget, fragments: ReadonlyArray<IEmbeddedFragment>): Promise<Result<number>>;
+
+  /**
+   * Remove every fragment for the scope-qualified `target`. Returns the removed
+   * target. Idempotent — removing a target with no fragments still succeeds.
+   */
+  remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
+
+  /**
+   * Return the `topK` nearest fragments to `vector`, in descending score order,
+   * each hit carrying its record `target` and fragment `locator`. When
+   * `maxPerRecord` is supplied, no more than that many fragments of any single
+   * record appear in the result — the cap is applied during selection (before the
+   * `topK` cut) so one long document cannot crowd out others.
+   */
+  query(
+    vector: Float32Array,
+    topK: number,
+    maxPerRecord?: 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
@@ -74,6 +155,18 @@ export interface IVectorIndex {
  */
 export type MemoryEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<Float32Array>>;
 
+/**
+ * The fragment-granular sibling of {@link MemoryEmbedder}: chunks a record's body
+ * and embeds each chunk, returning one {@link IEmbeddedFragment} per chunk. The
+ * chunking policy (window size, overlap) lives entirely in the consumer's embedder
+ * — the core stays chunking-agnostic, exactly as it stays embedder-agnostic for
+ * the record-granular path. Used by the store's fragment-embed-on-write hook.
+ * @public
+ */
+export type FragmentEmbedder = (
+  record: IMemoryRecord<unknown>
+) => Promise<Result<ReadonlyArray<IEmbeddedFragment>>>;
+
 /**
  * A record paired with its scope-qualified {@link IEdgeTarget | address}, as
  * yielded by {@link IMemoryRecordSource.list}. The address is required because

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

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

package/src/test/unit/store/fragmentEmbedOnWrite.test.ts

@@ -0,0 +1,349 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import '@fgv/ts-utils-jest';
+import { Converters, Logging, Result, fail, succeed } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-json-base';
+import {
+  BodyConverterRegistry,
+  EntityId,
+  FileTreeMemoryStore,
+  FragmentSemanticRetriever,
+  IBodyConverterRegistry,
+  IEdgeTarget,
+  IEmbeddedFragment,
+  IFragmentVectorIndex,
+  IIdentityCodec,
+  IMemoryRecord,
+  IVectorQueryHit,
+  InMemoryFragmentCosineIndex,
+  Kind,
+  KnowledgeIdentityCodec,
+  MemoryCapCullPolicy,
+  MemoryId,
+  MemoryScopeKey,
+  MtmIdentityCodec,
+  IWritePolicy,
+  envelopeConverter
+} from '../../../index';
+
+const knowledgeKind: Kind = 'knowledge' as Kind;
+const mtmKind: Kind = 'mtm' as Kind;
+
+function mutableRoot(): FileTree.IMutableFileTreeDirectoryItem {
+  const tree = FileTree.inMemory([], { mutable: true }).orThrow();
+  const root = tree.getDirectory('/').orThrow();
+  if (!FileTree.isMutableDirectoryItem(root)) {
+    throw new Error('expected a mutable root directory');
+  }
+  return root;
+}
+
+function makeRecord(
+  id: string,
+  body: string,
+  kind: string = 'knowledge',
+  entityId?: string
+): IMemoryRecord<unknown> {
+  return {
+    envelope: envelopeConverter
+      .convert({
+        id,
+        entityId: entityId ?? id,
+        kind,
+        tags: [],
+        links: [],
+        created: 0,
+        updated: 0,
+        seq: 0,
+        contentHash: '',
+        provenance: { source: 'agent' }
+      })
+      .orThrow(),
+    body
+  };
+}
+
+/** Deterministic keyword-count feature space (no network), shared with the query side. */
+const MARKERS: ReadonlyArray<string> = ['cat', 'dog', 'fish'];
+function featureVector(text: string): Float32Array {
+  const lower: string = text.toLowerCase();
+  return Float32Array.from(MARKERS.map((m) => lower.split(m).length - 1));
+}
+
+/**
+ * Fragment embedder: chunks the body into whitespace-delimited words, emitting one
+ * fragment per word with its true `[start, end)` character offsets and a feature
+ * vector for that word. Models the consumer-owned chunking policy.
+ */
+const fragmentEmbed = (r: IMemoryRecord<unknown>): Promise<Result<ReadonlyArray<IEmbeddedFragment>>> =>
+  Promise.resolve(
+    Converters.string
+      .convert(r.body)
+      .withErrorFormat((msg) => `cannot embed fragments: body is not a string: ${msg}`)
+      .onSuccess((body) => {
+        const fragments: IEmbeddedFragment[] = [];
+        const re: RegExp = /\S+/g;
+        let m: RegExpExecArray | null = re.exec(body);
+        while (m !== null) {
+          fragments.push({
+            locator: { start: m.index, end: m.index + m[0].length },
+            vector: featureVector(m[0])
+          });
+          m = re.exec(body);
+        }
+        return succeed(fragments);
+      })
+  );
+
+const queryEmbed = (text: string): Promise<Result<Float32Array>> =>
+  Promise.resolve(succeed(featureVector(text)));
+
+/** Records addFragments/remove call order and can be configured to fail either op. */
+class SpyFragmentIndex implements IFragmentVectorIndex {
+  public readonly calls: string[] = [];
+  public failAdd: boolean = false;
+  public failRemove: boolean = false;
+  private readonly _inner: InMemoryFragmentCosineIndex = InMemoryFragmentCosineIndex.create().orThrow();
+
+  public async addFragments(
+    target: IEdgeTarget,
+    fragments: ReadonlyArray<IEmbeddedFragment>
+  ): Promise<Result<number>> {
+    this.calls.push(`add:${target.id}:${fragments.length}`);
+    return this.failAdd ? fail('add boom') : this._inner.addFragments(target, fragments);
+  }
+  public async remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>> {
+    this.calls.push(`remove:${target.id}`);
+    return this.failRemove ? fail('remove boom') : this._inner.remove(target);
+  }
+  public query(
+    vector: Float32Array,
+    topK: number,
+    maxPerRecord?: number
+  ): Promise<Result<ReadonlyArray<IVectorQueryHit>>> {
+    return this._inner.query(vector, topK, maxPerRecord);
+  }
+}
+
+function knowledgeStore(params: {
+  fragmentIndex?: IFragmentVectorIndex;
+  fragmentEmbedder?: (r: IMemoryRecord<unknown>) => Promise<Result<ReadonlyArray<IEmbeddedFragment>>>;
+  logger?: Logging.ILogger;
+}): FileTreeMemoryStore {
+  const registry: IBodyConverterRegistry = BodyConverterRegistry.create().orThrow();
+  registry.register(knowledgeKind, Converters.string);
+  return FileTreeMemoryStore.create({
+    root: mutableRoot(),
+    registry,
+    codecs: new Map<Kind, IIdentityCodec>([[knowledgeKind, new KnowledgeIdentityCodec()]]),
+    fragmentIndex: params.fragmentIndex,
+    fragmentEmbedder: params.fragmentEmbedder,
+    logger: params.logger
+  }).orThrow();
+}
+
+describe('FileTreeMemoryStore fragment-embed-on-write', () => {
+  describe('when wired', () => {
+    test('embeds fragments on write and indexes them (queryable by span)', async () => {
+      const index = InMemoryFragmentCosineIndex.create().orThrow();
+      const store = knowledgeStore({ fragmentIndex: index, fragmentEmbedder: fragmentEmbed });
+      expect(await store.put(makeRecord('doc-a', 'cat dog'))).toSucceed();
+      // Two words → two fragments.
+      expect(index.recordCount).toBe(1);
+      expect(index.fragmentCount).toBe(2);
+      // A query for 'cat' surfaces the 'cat' span [0,3], not the 'dog' span.
+      expect(await index.query(featureVector('cat'), 1)).toSucceedAndSatisfy(
+        (hits: ReadonlyArray<IVectorQueryHit>) => {
+          expect(hits[0].target.id).toBe('doc-a');
+          expect(hits[0].locator).toEqual({ start: 0, end: 3 });
+        }
+      );
+    });
+
+    test('stamps nothing on the record (fragments have no per-record embeddingRef)', async () => {
+      const index = InMemoryFragmentCosineIndex.create().orThrow();
+      const store = knowledgeStore({ fragmentIndex: index, fragmentEmbedder: fragmentEmbed });
+      expect(await store.put(makeRecord('doc-a', 'cat dog'))).toSucceedAndSatisfy(
+        (record: IMemoryRecord<unknown>) => {
+          expect(record.envelope.embeddingRef).toBeUndefined();
+        }
+      );
+    });
+
+    test('re-embeds on a content change via whole-record replace', async () => {
+      const spy = new SpyFragmentIndex();
+      const store = knowledgeStore({ fragmentIndex: spy, fragmentEmbedder: fragmentEmbed });
+      (await store.put(makeRecord('doc-a', 'cat'))).orThrow();
+      (await store.put(makeRecord('doc-a', 'dog fish'))).orThrow();
+      // First write: 1 fragment; second: 2 fragments, replacing the first.
+      expect(spy.calls).toEqual(['add:doc-a:1', 'add:doc-a:2']);
+      // The 'cat' fragment is gone — the new 'dog'/'fish' spans are orthogonal to a
+      // 'cat' query (best score 0), proving the whole-record replace dropped it.
+      expect(await spy.query(featureVector('cat'), 5)).toSucceedAndSatisfy(
+        (hits: ReadonlyArray<IVectorQueryHit>) => {
+          expect(hits.every((h) => h.score === 0)).toBe(true);
+        }
+      );
+      expect(await spy.query(featureVector('fish'), 1)).toSucceedAndSatisfy(
+        (hits: ReadonlyArray<IVectorQueryHit>) => {
+          expect(hits[0].score).toBeCloseTo(1);
+        }
+      );
+    });
+
+    test('does not re-embed a dedup no-op (identical content)', async () => {
+      const spy = new SpyFragmentIndex();
+      const store = knowledgeStore({ fragmentIndex: spy, fragmentEmbedder: fragmentEmbed });
+      (await store.put(makeRecord('doc-a', 'cat'))).orThrow();
+      (await store.put(makeRecord('doc-a', 'cat'))).orThrow();
+      expect(spy.calls).toEqual(['add:doc-a:1']);
+    });
+
+    test('removes the fragments on delete', async () => {
+      const spy = new SpyFragmentIndex();
+      const store = knowledgeStore({ fragmentIndex: spy, fragmentEmbedder: fragmentEmbed });
+      (await store.put(makeRecord('doc-a', 'cat dog'))).orThrow();
+      expect(await store.delete(knowledgeKind, 'doc-a' as unknown as EntityId)).toSucceedWith(
+        'doc-a' as MemoryId
+      );
+      expect(spy.calls).toEqual(['add:doc-a:2', 'remove:doc-a']);
+      expect(await spy.query(featureVector('cat'), 5)).toSucceedWith([]);
+    });
+
+    test('removes evicted fragments on cap-cull eviction', async () => {
+      const index = InMemoryFragmentCosineIndex.create().orThrow();
+      const capCull: IWritePolicy = MemoryCapCullPolicy.create({
+        maxRecords: 2,
+        mutableFields: ['body', 'tags', 'links', 'provenance', 'embeddingRef']
+      }).orThrow();
+      const registry: IBodyConverterRegistry = BodyConverterRegistry.create().orThrow();
+      registry.register(mtmKind, Converters.string);
+      const store = FileTreeMemoryStore.create({
+        root: mutableRoot(),
+        registry,
+        codecs: new Map<Kind, IIdentityCodec>([[mtmKind, new MtmIdentityCodec()]]),
+        writePolicies: new Map<Kind, IWritePolicy>([[mtmKind, capCull]]),
+        fragmentIndex: index,
+        fragmentEmbedder: fragmentEmbed
+      }).orThrow();
+
+      (await store.put(makeRecord('turn-0', 'cat', 'mtm', 'conv-1:0'))).orThrow();
+      (await store.put(makeRecord('turn-1', 'dog', 'mtm', 'conv-1:1'))).orThrow();
+      (await store.put(makeRecord('turn-2', 'fish', 'mtm', 'conv-1:2'))).orThrow();
+      // turn-0 evicted from the store AND its fragments from the index.
+      expect(index.recordCount).toBe(2);
+      expect(await index.query(featureVector('cat'), 5)).toSucceedAndSatisfy(
+        (hits: ReadonlyArray<IVectorQueryHit>) => {
+          expect(hits.map((h) => h.target.id)).not.toContain('turn-0');
+        }
+      );
+    });
+
+    test('persists the record (best-effort) and logs when fragment embedding fails', async () => {
+      const index = InMemoryFragmentCosineIndex.create().orThrow();
+      const logger = new Logging.InMemoryLogger();
+      const failEmbed = (): Promise<Result<ReadonlyArray<IEmbeddedFragment>>> =>
+        Promise.resolve(fail('no model'));
+      const store = knowledgeStore({ fragmentIndex: index, fragmentEmbedder: failEmbed, logger });
+      expect(await store.put(makeRecord('doc-a', 'cat'))).toSucceed();
+      expect(await store.getById('knowledge' as MemoryScopeKey, 'doc-a' as MemoryId)).toSucceedAndSatisfy(
+        (record: IMemoryRecord<unknown> | undefined) => {
+          expect(record?.envelope.id).toBe('doc-a');
+        }
+      );
+      expect(index.recordCount).toBe(0);
+      expect(logger.logged.some((m) => /fragment embedding 'doc-a' failed.*no model/i.test(m))).toBe(true);
+    });
+
+    test('persists the record (best-effort) and logs when the fragment add fails', async () => {
+      const spy = new SpyFragmentIndex();
+      spy.failAdd = true;
+      const logger = new Logging.InMemoryLogger();
+      const store = knowledgeStore({ fragmentIndex: spy, fragmentEmbedder: fragmentEmbed, logger });
+      expect(await store.put(makeRecord('doc-a', 'cat'))).toSucceed();
+      expect(await store.getById('knowledge' as MemoryScopeKey, 'doc-a' as MemoryId)).toSucceedAndSatisfy(
+        (record: IMemoryRecord<unknown> | undefined) => {
+          expect(record?.envelope.id).toBe('doc-a');
+        }
+      );
+      expect(logger.logged.some((m) => /fragment add for 'doc-a' failed.*add boom/i.test(m))).toBe(true);
+    });
+
+    test('best-effort embed survives a throwing/rejecting fragment embedder', async () => {
+      const index = InMemoryFragmentCosineIndex.create().orThrow();
+      const logger = new Logging.InMemoryLogger();
+      const throwingEmbed = (): Promise<Result<ReadonlyArray<IEmbeddedFragment>>> =>
+        Promise.reject(new Error('embedder kaboom'));
+      const store = knowledgeStore({ fragmentIndex: index, fragmentEmbedder: throwingEmbed, logger });
+      expect(await store.put(makeRecord('doc-a', 'cat'))).toSucceed();
+      expect(index.recordCount).toBe(0);
+      expect(logger.logged.some((m) => /fragment embedding 'doc-a' threw.*embedder kaboom/i.test(m))).toBe(
+        true
+      );
+    });
+
+    test('a committed delete succeeds (best-effort) and logs when fragment removal fails', async () => {
+      const spy = new SpyFragmentIndex();
+      const logger = new Logging.InMemoryLogger();
+      const store = knowledgeStore({ fragmentIndex: spy, fragmentEmbedder: fragmentEmbed, logger });
+      (await store.put(makeRecord('doc-a', 'cat'))).orThrow();
+      spy.failRemove = true;
+      expect(await store.delete(knowledgeKind, 'doc-a' as unknown as EntityId)).toSucceedWith(
+        'doc-a' as MemoryId
+      );
+      expect(await store.getById('knowledge' as MemoryScopeKey, 'doc-a' as MemoryId)).toSucceedWith(
+        undefined
+      );
+      expect(logger.logged.some((m) => /fragment removal for 'doc-a' failed.*remove boom/i.test(m))).toBe(
+        true
+      );
+    });
+  });
+
+  describe('when unwired', () => {
+    test('a store without a fragment index or embedder does no fragment work', async () => {
+      const store = knowledgeStore({});
+      expect(await store.put(makeRecord('doc-a', 'cat'))).toSucceedAndSatisfy(
+        (record: IMemoryRecord<unknown>) => {
+          expect(record.envelope.embeddingRef).toBeUndefined();
+        }
+      );
+    });
+
+    test('a fragment index without an embedder is fully inert (no add or remove)', async () => {
+      const spy = new SpyFragmentIndex();
+      const store = knowledgeStore({ fragmentIndex: spy });
+      (await store.put(makeRecord('doc-a', 'cat'))).orThrow();
+      (await store.delete(knowledgeKind, 'doc-a' as unknown as EntityId)).orThrow();
+      expect(spy.calls).toEqual([]);
+    });
+  });
+
+  describe('fragment discovery end-to-end', () => {
+    test('a wired store + InMemoryFragmentCosineIndex + FragmentSemanticRetriever returns per-span hits', async () => {
+      const index = InMemoryFragmentCosineIndex.create().orThrow();
+      const store = knowledgeStore({ fragmentIndex: index, fragmentEmbedder: fragmentEmbed });
+      (await store.put(makeRecord('doc-a', 'cat cat dog'))).orThrow();
+      (await store.put(makeRecord('doc-b', 'fish fish'))).orThrow();
+
+      const retriever = FragmentSemanticRetriever.create({
+        backend: { fragmentIndex: index, embedQuery: queryEmbed }
+      }).orThrow();
+      expect(retriever.capabilities.supportsFragmentRecall).toBe(true);
+
+      // maxPerRecord=1 keeps doc-a's two 'cat' spans from crowding out the field.
+      expect(await retriever.retrieve({ semantic: 'cat', topK: 5, maxPerRecord: 1 })).toSucceedAndSatisfy(
+        (hits: ReadonlyArray<IVectorQueryHit>) => {
+          // The top hit is a 'cat' span in doc-a; the doc-a cap is honored.
+          expect(hits[0].target.id).toBe('doc-a');
+          expect(hits[0].locator).toEqual({ start: 0, end: 3 });
+          const perRecord = hits.filter((h) => h.target.id === 'doc-a');
+          expect(perRecord).toHaveLength(1);
+        }
+      );
+    });
+  });
+});