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

package/.rush/temp/{cbbdbe09515171b4eba8f2592be2dace1e4e8142.tar.log → 285f03271c27ef724d49e730c0db58d9e4ac1a44.tar.log}

@@ -1,5 +1,5 @@
-Start time: Tue Jul 14 2026 06:13:34 GMT+0000 (Coordinated Universal Time)
-Invoking "/usr/bin/tar -c -f /home/runner/work/fgv/fgv/common/temp/build-cache/cbbdbe09515171b4eba8f2592be2dace1e4e8142-c6a08a434367e77c.temp -z --files-from=-"
+Start time: Mon Jul 20 2026 00:41:10 GMT+0000 (Coordinated Universal Time)
+Invoking "/usr/bin/tar -c -f /home/runner/work/fgv/fgv/common/temp/build-cache/285f03271c27ef724d49e730c0db58d9e4ac1a44-b5b9975b621910d8.temp -z --files-from=-"
 
 ======= BEGIN PROCESS INPUT ======
 .rush/temp/operation/build/all.log
@@ -33,6 +33,8 @@ dist/packlets/observe/memoryObservationStore.js
 dist/packlets/observe/memoryObservationStore.js.map
 dist/packlets/observe/observer.js
 dist/packlets/observe/observer.js.map
+dist/packlets/retrieve/fragmentSemanticRetriever.js
+dist/packlets/retrieve/fragmentSemanticRetriever.js.map
 dist/packlets/retrieve/hybridRetriever.js
 dist/packlets/retrieve/hybridRetriever.js.map
 dist/packlets/retrieve/index.js
@@ -77,6 +79,8 @@ dist/packlets/types/writePolicy.js
 dist/packlets/types/writePolicy.js.map
 dist/packlets/vector/inMemoryCosineIndex.js
 dist/packlets/vector/inMemoryCosineIndex.js.map
+dist/packlets/vector/inMemoryFragmentCosineIndex.js
+dist/packlets/vector/inMemoryFragmentCosineIndex.js.map
 dist/packlets/vector/index.js
 dist/packlets/vector/index.js.map
 dist/packlets/vector/vectorIndex.js
@@ -97,6 +101,8 @@ dist/test/unit/ingest/orchestrator.test.js
 dist/test/unit/ingest/orchestrator.test.js.map
 dist/test/unit/observe/memoryObservationStore.test.js
 dist/test/unit/observe/memoryObservationStore.test.js.map
+dist/test/unit/retrieve/fragmentSemanticRetriever.test.js
+dist/test/unit/retrieve/fragmentSemanticRetriever.test.js.map
 dist/test/unit/retrieve/linkTraversalRetriever.test.js
 dist/test/unit/retrieve/linkTraversalRetriever.test.js.map
 dist/test/unit/retrieve/retrievers.test.js
@@ -109,6 +115,10 @@ dist/test/unit/store/embedOnWrite.test.js
 dist/test/unit/store/embedOnWrite.test.js.map
 dist/test/unit/store/fileTreeMemoryStore.test.js
 dist/test/unit/store/fileTreeMemoryStore.test.js.map
+dist/test/unit/store/fragmentEmbedOnWrite.test.js
+dist/test/unit/store/fragmentEmbedOnWrite.test.js.map
+dist/test/unit/store/lenientOpen.test.js
+dist/test/unit/store/lenientOpen.test.js.map
 dist/test/unit/store/listScoped.test.js
 dist/test/unit/store/listScoped.test.js.map
 dist/test/unit/store/observations.test.js
@@ -133,6 +143,8 @@ dist/test/unit/types/writePolicy.test.js
 dist/test/unit/types/writePolicy.test.js.map
 dist/test/unit/vector/inMemoryCosineIndex.test.js
 dist/test/unit/vector/inMemoryCosineIndex.test.js.map
+dist/test/unit/vector/inMemoryFragmentCosineIndex.test.js
+dist/test/unit/vector/inMemoryFragmentCosineIndex.test.js.map
 dist/test/unit/vector/vectorIndex.test.js
 dist/test/unit/vector/vectorIndex.test.js.map
 dist/ts-agent-memory.d.ts
@@ -193,6 +205,10 @@ lib/packlets/observe/observer.d.ts
 lib/packlets/observe/observer.d.ts.map
 lib/packlets/observe/observer.js
 lib/packlets/observe/observer.js.map
+lib/packlets/retrieve/fragmentSemanticRetriever.d.ts
+lib/packlets/retrieve/fragmentSemanticRetriever.d.ts.map
+lib/packlets/retrieve/fragmentSemanticRetriever.js
+lib/packlets/retrieve/fragmentSemanticRetriever.js.map
 lib/packlets/retrieve/hybridRetriever.d.ts
 lib/packlets/retrieve/hybridRetriever.d.ts.map
 lib/packlets/retrieve/hybridRetriever.js
@@ -281,6 +297,10 @@ lib/packlets/vector/inMemoryCosineIndex.d.ts
 lib/packlets/vector/inMemoryCosineIndex.d.ts.map
 lib/packlets/vector/inMemoryCosineIndex.js
 lib/packlets/vector/inMemoryCosineIndex.js.map
+lib/packlets/vector/inMemoryFragmentCosineIndex.d.ts
+lib/packlets/vector/inMemoryFragmentCosineIndex.d.ts.map
+lib/packlets/vector/inMemoryFragmentCosineIndex.js
+lib/packlets/vector/inMemoryFragmentCosineIndex.js.map
 lib/packlets/vector/index.d.ts
 lib/packlets/vector/index.d.ts.map
 lib/packlets/vector/index.js
@@ -321,6 +341,10 @@ lib/test/unit/observe/memoryObservationStore.test.d.ts
 lib/test/unit/observe/memoryObservationStore.test.d.ts.map
 lib/test/unit/observe/memoryObservationStore.test.js
 lib/test/unit/observe/memoryObservationStore.test.js.map
+lib/test/unit/retrieve/fragmentSemanticRetriever.test.d.ts
+lib/test/unit/retrieve/fragmentSemanticRetriever.test.d.ts.map
+lib/test/unit/retrieve/fragmentSemanticRetriever.test.js
+lib/test/unit/retrieve/fragmentSemanticRetriever.test.js.map
 lib/test/unit/retrieve/linkTraversalRetriever.test.d.ts
 lib/test/unit/retrieve/linkTraversalRetriever.test.d.ts.map
 lib/test/unit/retrieve/linkTraversalRetriever.test.js
@@ -345,6 +369,14 @@ lib/test/unit/store/fileTreeMemoryStore.test.d.ts
 lib/test/unit/store/fileTreeMemoryStore.test.d.ts.map
 lib/test/unit/store/fileTreeMemoryStore.test.js
 lib/test/unit/store/fileTreeMemoryStore.test.js.map
+lib/test/unit/store/fragmentEmbedOnWrite.test.d.ts
+lib/test/unit/store/fragmentEmbedOnWrite.test.d.ts.map
+lib/test/unit/store/fragmentEmbedOnWrite.test.js
+lib/test/unit/store/fragmentEmbedOnWrite.test.js.map
+lib/test/unit/store/lenientOpen.test.d.ts
+lib/test/unit/store/lenientOpen.test.d.ts.map
+lib/test/unit/store/lenientOpen.test.js
+lib/test/unit/store/lenientOpen.test.js.map
 lib/test/unit/store/listScoped.test.d.ts
 lib/test/unit/store/listScoped.test.d.ts.map
 lib/test/unit/store/listScoped.test.js
@@ -393,6 +425,10 @@ lib/test/unit/vector/inMemoryCosineIndex.test.d.ts
 lib/test/unit/vector/inMemoryCosineIndex.test.d.ts.map
 lib/test/unit/vector/inMemoryCosineIndex.test.js
 lib/test/unit/vector/inMemoryCosineIndex.test.js.map
+lib/test/unit/vector/inMemoryFragmentCosineIndex.test.d.ts
+lib/test/unit/vector/inMemoryFragmentCosineIndex.test.d.ts.map
+lib/test/unit/vector/inMemoryFragmentCosineIndex.test.js
+lib/test/unit/vector/inMemoryFragmentCosineIndex.test.js.map
 lib/test/unit/vector/vectorIndex.test.d.ts
 lib/test/unit/vector/vectorIndex.test.d.ts.map
 lib/test/unit/vector/vectorIndex.test.js

package/.rush/temp/chunked-rush-logs/ts-agent-memory.build.chunks.jsonl

@@ -5,5 +5,5 @@
 {"kind":"O","text":"[build:lint] Using ESLint version 9.39.5\n"}
 {"kind":"O","text":"[build:api-extractor] Using API Extractor version 7.58.9\n"}
 {"kind":"O","text":"[build:api-extractor] Analysis will use the bundled TypeScript version 5.9.3\n"}
-{"kind":"O","text":" ---- build finished (26.015s) ---- \n"}
-{"kind":"O","text":"-------------------- Finished (26.02s) --------------------\n"}
+{"kind":"O","text":" ---- build finished (26.514s) ---- \n"}
+{"kind":"O","text":"-------------------- Finished (26.523s) --------------------\n"}

package/.rush/temp/operation/build/all.log

@@ -5,5 +5,5 @@ Invoking: heft build --clean
 [build:lint] Using ESLint version 9.39.5
 [build:api-extractor] Using API Extractor version 7.58.9
 [build:api-extractor] Analysis will use the bundled TypeScript version 5.9.3
- ---- build finished (26.015s) ---- 
--------------------- Finished (26.02s) --------------------
+ ---- build finished (26.514s) ---- 
+-------------------- Finished (26.523s) --------------------

package/.rush/temp/operation/build/log-chunks.jsonl

@@ -5,5 +5,5 @@
 {"kind":"O","text":"[build:lint] Using ESLint version 9.39.5\n"}
 {"kind":"O","text":"[build:api-extractor] Using API Extractor version 7.58.9\n"}
 {"kind":"O","text":"[build:api-extractor] Analysis will use the bundled TypeScript version 5.9.3\n"}
-{"kind":"O","text":" ---- build finished (26.015s) ---- \n"}
-{"kind":"O","text":"-------------------- Finished (26.02s) --------------------\n"}
+{"kind":"O","text":" ---- build finished (26.514s) ---- \n"}
+{"kind":"O","text":"-------------------- Finished (26.523s) --------------------\n"}

package/.rush/temp/operation/build/state.json

@@ -1,3 +1,3 @@
 {
-  "nonCachedDurationMs": 26865.358066
+  "nonCachedDurationMs": 27347.06894099999
 }

package/dist/packlets/retrieve/fragmentSemanticRetriever.js

@@ -0,0 +1,78 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+import { fail, succeed } from '@fgv/ts-utils';
+/**
+ * The loud-degradation message a {@link FragmentSemanticRetriever} returns when a
+ * fragment query is issued but no {@link IFragmentSemanticBackend | backend} is
+ * wired — the discovery surface NEVER answers a fragment query with a silent empty.
+ * @public
+ */
+export const FRAGMENT_SEMANTIC_UNWIRED_MESSAGE = 'fragment recall: no fragment index is wired; wire an IFragmentSemanticBackend to enable sub-document search';
+/**
+ * The sub-document semantic-search retriever — the "discovery" half of a
+ * search-then-read contract. It embeds a fragment query, queries the
+ * {@link IFragmentVectorIndex}, and returns the raw per-fragment
+ * {@link IVectorQueryHit | hits} (each carrying a record `target` AND the matched
+ * `locator`), NOT resolved records: the consumer re-reads each record and slices it
+ * by the locator on its own read side.
+ *
+ * @remarks
+ * Deliberately NOT an {@link IMemoryRetriever}: memory recall is record-granular and
+ * returns records; fragment discovery is span-granular and returns locators. Keeping
+ * it a distinct surface matches the consumer contract (memory stays record-granular;
+ * sub-document knowledge uses a separate fragment index) and avoids overloading the
+ * record retriever's return type with a locator that only makes sense here.
+ *
+ * When no backend is wired, `supportsFragmentRecall` is `false` and any fragment
+ * query degrades loudly ({@link FRAGMENT_SEMANTIC_UNWIRED_MESSAGE}) — it NEVER
+ * returns a silent empty. A consumer-supplied backend that rejects (throws) is
+ * normalized into a `Failure`.
+ * @public
+ */
+export class FragmentSemanticRetriever {
+    constructor(backend) {
+        this._backend = backend;
+    }
+    /** What this retriever can do given its wiring. */
+    get capabilities() {
+        return { supportsFragmentRecall: this._backend !== undefined };
+    }
+    /** Family-convention factory. */
+    static create(params) {
+        return succeed(new FragmentSemanticRetriever(params.backend));
+    }
+    /**
+     * Embed `query.semantic`, query the fragment index, and return the per-fragment
+     * hits in descending score order. Fails loudly when no backend is wired.
+     */
+    async retrieve(query) {
+        if (this._backend === undefined) {
+            return fail(FRAGMENT_SEMANTIC_UNWIRED_MESSAGE);
+        }
+        const backend = this._backend;
+        // Consumer-supplied hooks may throw; normalize both a returned `fail` and a
+        // rejection into a single `fragment recall: <label> failed` Failure so
+        // `retrieve` always honors its `Promise<Result<...>>` contract.
+        const embedded = await FragmentSemanticRetriever._callBackend('query embedding', () => backend.embedQuery(query.semantic));
+        if (embedded.isFailure()) {
+            return fail(embedded.message);
+        }
+        return FragmentSemanticRetriever._callBackend('fragment query', () => { var _a; return backend.fragmentIndex.query(embedded.value, (_a = query.topK) !== null && _a !== void 0 ? _a : 10, query.maxPerRecord); });
+    }
+    /**
+     * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`
+     * and a thrown/rejected promise into a single `fragment recall: <label> failed`
+     * `Failure`.
+     */
+    static async _callBackend(label, op) {
+        try {
+            return (await op()).withErrorFormat((msg) => `fragment recall: ${label} failed: ${msg}`);
+        }
+        catch (err) {
+            return fail(`fragment recall: ${label} failed: ${String(err)}`);
+        }
+    }
+}
+//# sourceMappingURL=fragmentSemanticRetriever.js.map

package/dist/packlets/retrieve/fragmentSemanticRetriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragmentSemanticRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/fragmentSemanticRetriever.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,IAAI,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAItD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAC5C,6GAA6G,CAAC;AA0ChH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,yBAAyB;IAGpC,YAAoB,OAA6C;QAC/D,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,mDAAmD;IACnD,IAAW,YAAY;QACrB,OAAO,EAAE,sBAAsB,EAAE,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;IACjE,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM,CAAC,MAEpB;QACC,OAAO,OAAO,CAAC,IAAI,yBAAyB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAChE,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,QAAQ,CAAC,KAAqB;QACzC,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAChC,OAAO,IAAI,CAAC,iCAAiC,CAAC,CAAC;QACjD,CAAC;QACD,MAAM,OAAO,GAA6B,IAAI,CAAC,QAAQ,CAAC;QACxD,4EAA4E;QAC5E,uEAAuE;QACvE,gEAAgE;QAChE,MAAM,QAAQ,GAAyB,MAAM,yBAAyB,CAAC,YAAY,CACjF,iBAAiB,EACjB,GAAG,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,CACzC,CAAC;QACF,IAAI,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;QACD,OAAO,yBAAyB,CAAC,YAAY,CAAC,gBAAgB,EAAE,GAAG,EAAE,WACnE,OAAA,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAA,KAAK,CAAC,IAAI,mCAAI,EAAE,EAAE,KAAK,CAAC,YAAY,CAAC,CAAA,EAAA,CAClF,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACK,MAAM,CAAC,KAAK,CAAC,YAAY,CAAI,KAAa,EAAE,EAA4B;QAC9E,IAAI,CAAC;YACH,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,oBAAoB,KAAK,YAAY,GAAG,EAAE,CAAC,CAAC;QAC3F,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,oBAAoB,KAAK,YAAY,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, fail, succeed } from '@fgv/ts-utils';\nimport { IFragmentVectorIndex, IVectorQueryHit } from '../vector';\nimport { QueryEmbedder } from './semanticRetriever';\n\n/**\n * The loud-degradation message a {@link FragmentSemanticRetriever} returns when a\n * fragment query is issued but no {@link IFragmentSemanticBackend | backend} is\n * wired — the discovery surface NEVER answers a fragment query with a silent empty.\n * @public\n */\nexport const FRAGMENT_SEMANTIC_UNWIRED_MESSAGE: string =\n  'fragment recall: no fragment index is wired; wire an IFragmentSemanticBackend to enable sub-document search';\n\n/**\n * The fragment backend wired into a {@link FragmentSemanticRetriever}: the fragment\n * index to query and the embedder that turns the query text into a vector. Both are\n * required together — a fragment index is useless without a way to embed the query.\n * @public\n */\nexport interface IFragmentSemanticBackend {\n  /** The fragment-granular vector index to query. */\n  readonly fragmentIndex: IFragmentVectorIndex;\n  /** Turns the query text into a vector. */\n  readonly embedQuery: QueryEmbedder;\n}\n\n/**\n * A sub-document semantic-search request: the natural-language `semantic` text to\n * match, an optional `topK` result cap (default 10), and an optional\n * `maxPerRecord` cap that keeps one long document from monopolizing the result.\n * @public\n */\nexport interface IFragmentQuery {\n  /** The natural-language text to embed and match against stored fragments. */\n  readonly semantic: string;\n  /** Maximum number of fragment hits to return. Defaults to 10. */\n  readonly topK?: number;\n  /**\n   * Maximum number of fragments any single record may contribute to the result.\n   * Applied during selection (before the `topK` cut). Omit for uncapped.\n   */\n  readonly maxPerRecord?: number;\n}\n\n/**\n * What a {@link FragmentSemanticRetriever} can do given its wiring.\n * @public\n */\nexport interface IFragmentRetrieverCapabilities {\n  /** `true` when a fragment backend is wired and fragment recall is operational. */\n  readonly supportsFragmentRecall: boolean;\n}\n\n/**\n * The sub-document semantic-search retriever — the \"discovery\" half of a\n * search-then-read contract. It embeds a fragment query, queries the\n * {@link IFragmentVectorIndex}, and returns the raw per-fragment\n * {@link IVectorQueryHit | hits} (each carrying a record `target` AND the matched\n * `locator`), NOT resolved records: the consumer re-reads each record and slices it\n * by the locator on its own read side.\n *\n * @remarks\n * Deliberately NOT an {@link IMemoryRetriever}: memory recall is record-granular and\n * returns records; fragment discovery is span-granular and returns locators. Keeping\n * it a distinct surface matches the consumer contract (memory stays record-granular;\n * sub-document knowledge uses a separate fragment index) and avoids overloading the\n * record retriever's return type with a locator that only makes sense here.\n *\n * When no backend is wired, `supportsFragmentRecall` is `false` and any fragment\n * query degrades loudly ({@link FRAGMENT_SEMANTIC_UNWIRED_MESSAGE}) — it NEVER\n * returns a silent empty. A consumer-supplied backend that rejects (throws) is\n * normalized into a `Failure`.\n * @public\n */\nexport class FragmentSemanticRetriever {\n  private readonly _backend: IFragmentSemanticBackend | undefined;\n\n  private constructor(backend: IFragmentSemanticBackend | undefined) {\n    this._backend = backend;\n  }\n\n  /** What this retriever can do given its wiring. */\n  public get capabilities(): IFragmentRetrieverCapabilities {\n    return { supportsFragmentRecall: this._backend !== undefined };\n  }\n\n  /** Family-convention factory. */\n  public static create(params: {\n    readonly backend?: IFragmentSemanticBackend;\n  }): Result<FragmentSemanticRetriever> {\n    return succeed(new FragmentSemanticRetriever(params.backend));\n  }\n\n  /**\n   * Embed `query.semantic`, query the fragment index, and return the per-fragment\n   * hits in descending score order. Fails loudly when no backend is wired.\n   */\n  public async retrieve(query: IFragmentQuery): Promise<Result<ReadonlyArray<IVectorQueryHit>>> {\n    if (this._backend === undefined) {\n      return fail(FRAGMENT_SEMANTIC_UNWIRED_MESSAGE);\n    }\n    const backend: IFragmentSemanticBackend = this._backend;\n    // Consumer-supplied hooks may throw; normalize both a returned `fail` and a\n    // rejection into a single `fragment recall: <label> failed` Failure so\n    // `retrieve` always honors its `Promise<Result<...>>` contract.\n    const embedded: Result<Float32Array> = await FragmentSemanticRetriever._callBackend(\n      'query embedding',\n      () => backend.embedQuery(query.semantic)\n    );\n    if (embedded.isFailure()) {\n      return fail(embedded.message);\n    }\n    return FragmentSemanticRetriever._callBackend('fragment query', () =>\n      backend.fragmentIndex.query(embedded.value, query.topK ?? 10, query.maxPerRecord)\n    );\n  }\n\n  /**\n   * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`\n   * and a thrown/rejected promise into a single `fragment recall: <label> failed`\n   * `Failure`.\n   */\n  private static async _callBackend<T>(label: string, op: () => Promise<Result<T>>): Promise<Result<T>> {\n    try {\n      return (await op()).withErrorFormat((msg) => `fragment recall: ${label} failed: ${msg}`);\n    } catch (err) {\n      return fail(`fragment recall: ${label} failed: ${String(err)}`);\n    }\n  }\n}\n"]}

package/dist/packlets/retrieve/index.js

@@ -8,6 +8,7 @@ export * from './linkTraversalRetriever';
 export * from './tagRetriever';
 export * from './structuredFilterRetriever';
 export * from './semanticRetriever';
+export * from './fragmentSemanticRetriever';
 export * from './temporalRetrievers';
 export * from './hybridRetriever';
 //# sourceMappingURL=index.js.map

package/dist/packlets/retrieve/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './retriever';\nexport * from './recencyRetriever';\nexport * from './linkTraversalRetriever';\nexport * from './tagRetriever';\nexport * from './structuredFilterRetriever';\nexport * from './semanticRetriever';\nexport * from './temporalRetrievers';\nexport * from './hybridRetriever';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './retriever';\nexport * from './recencyRetriever';\nexport * from './linkTraversalRetriever';\nexport * from './tagRetriever';\nexport * from './structuredFilterRetriever';\nexport * from './semanticRetriever';\nexport * from './fragmentSemanticRetriever';\nexport * from './temporalRetrievers';\nexport * from './hybridRetriever';\n"]}

package/dist/packlets/store/fileTreeMemoryStore.js

@@ -2,7 +2,7 @@
  * Copyright (c) 2026 Erik Fortune
  * SPDX-License-Identifier: MIT
  */
-import { Hash, Logging, fail, mapResults, succeed } from '@fgv/ts-utils';
+import { Hash, Logging, fail, mapResults, mapSuccess, succeed } from '@fgv/ts-utils';
 import { FileTree } from '@fgv/ts-json-base';
 import { DEFAULT_DEDUP_SCOPE, KnowledgeLwwPolicy, isTemporalIdentityCodec, isTemporalRecord, isVersionCurrent, selectCurrentVersion, selectVersionAsOf } from '../types';
 import { parseMemoryFile, serializeMemoryFile } from '../converters';
@@ -41,10 +41,24 @@ export class FileTreeMemoryStore {
         this._logger = params.logger;
         this._vectorIndex = params.vectorIndex;
         this._embed = params.embed;
+        this._fragmentIndex = params.fragmentIndex;
+        this._fragmentEmbedder = params.fragmentEmbedder;
+        this._skippedRecords = [];
         this._seq = 0;
         this._observationSeq = 0;
         this._writeTail = Promise.resolve();
     }
+    /**
+     * Records the initial vault walk could not parse or validate and quarantined
+     * (not indexed). Non-empty only when the store was opened with
+     * {@link MemoryRecordErrorMode | `onRecordError: 'skip'`} AND at least one
+     * record failed to load. Each entry identifies the offending file so a host
+     * can repair it; the file itself is never deleted or mutated, so a later open
+     * (after the body converter is fixed) re-indexes it.
+     */
+    get skippedRecords() {
+        return this._skippedRecords;
+    }
     /**
      * Family-convention factory. Builds the derived index and a default LWW
      * policy, then performs an initial FileTree walk so an existing vault is
@@ -52,7 +66,7 @@ export class FileTreeMemoryStore {
      */
     static create(params) {
         return KnowledgeLwwPolicy.create().onSuccess((defaultPolicy) => MemoryIndex.create().onSuccess((index) => {
-            var _a, _b, _c, _d, _e, _f, _g;
+            var _a, _b, _c, _d, _e, _f, _g, _h;
             const store = new FileTreeMemoryStore({
                 root: params.root,
                 registry: params.registry,
@@ -67,9 +81,11 @@ export class FileTreeMemoryStore {
                 observers: (_f = params.observers) !== null && _f !== void 0 ? _f : [],
                 logger: (_g = params.logger) !== null && _g !== void 0 ? _g : new Logging.NoOpLogger(),
                 vectorIndex: params.vectorIndex,
-                embed: params.embed
+                embed: params.embed,
+                fragmentIndex: params.fragmentIndex,
+                fragmentEmbedder: params.fragmentEmbedder
             });
-            return store._initialIndex().onSuccess(() => succeed(store));
+            return store._initialIndex((_h = params.onRecordError) !== null && _h !== void 0 ? _h : 'fail').onSuccess(() => succeed(store));
         }));
     }
     /** {@inheritDoc IMemoryStore.get} */
@@ -386,6 +402,7 @@ export class FileTreeMemoryStore {
         return this._buildRecord(record, body, existing, policy, hash)
             .onSuccess((built) => succeed(this._stampRank(built)))
             .thenOnSuccess((built) => this._embedOnWrite(built, scope))
+            .thenOnSuccess((built) => this._embedFragmentsOnWrite(built, scope))
             .onSuccess((embeddedBuilt) => this._persist(embeddedBuilt, scope, idStem))
             .thenOnSuccess(async (persisted) => {
             // Everything after the authoritative `_persist` commit is best-effort and
@@ -428,6 +445,45 @@ export class FileTreeMemoryStore {
         }
         return succeed({ envelope: Object.assign(Object.assign({}, built.envelope), { embeddingRef: added.value }), body: built.body });
     }
+    /**
+     * Best-effort fragment-embed-on-write. When a fragment index AND a fragment
+     * embedder are wired, chunks + embeds the built record and replaces its
+     * fragments in the index (`addFragments` is whole-record-replace, so a re-authored
+     * document never leaves stale fragments behind — no explicit remove needed). A
+     * failure (returned `fail` OR a thrown/rejected hook) is logged and the record is
+     * returned unchanged — the put still persists, and the fragment index is a derived
+     * view a later `rebuild` reconciles. Unlike {@link FileTreeMemoryStore._embedOnWrite}
+     * it stamps nothing on the record (fragments have no per-record `embeddingRef`
+     * analog). A pass-through no-op when unwired (byte-identical record).
+     */
+    async _embedFragmentsOnWrite(built, scope) {
+        if (this._fragmentIndex === undefined || this._fragmentEmbedder === undefined) {
+            return succeed(built);
+        }
+        const fragmentIndex = this._fragmentIndex;
+        const fragmentEmbedder = this._fragmentEmbedder;
+        const target = { scope, id: built.envelope.id };
+        const embedded = await this._tryVectorOp(() => fragmentEmbedder(built), `fragment embedding '${built.envelope.id}'`);
+        if (embedded.isFailure()) {
+            return succeed(built);
+        }
+        await this._tryVectorOp(() => fragmentIndex.addFragments(target, embedded.value), `fragment add for '${built.envelope.id}'`);
+        return succeed(built);
+    }
+    /**
+     * Best-effort fragment removal. A no-op unless the full fragment lifecycle is
+     * wired (both an index AND an embedder), so an unwired store does no fragment
+     * work and behaves byte-identically. Failures are logged, never surfaced — a
+     * committed delete/eviction must not fail because a derived fragment index could
+     * not be pruned.
+     */
+    async _removeFragmentsBestEffort(target) {
+        if (this._fragmentIndex === undefined || this._fragmentEmbedder === undefined) {
+            return;
+        }
+        const fragmentIndex = this._fragmentIndex;
+        await this._tryVectorOp(() => fragmentIndex.remove(target), `fragment removal for '${target.id}'`);
+    }
     /**
      * Evict the records named by a `cull-oldest` decision, best-effort. Runs only
      * after the authoritative `_persist`, so a failed eviction is logged (never
@@ -460,6 +516,7 @@ export class FileTreeMemoryStore {
     async _removeEvictedVectors(evicted, scope) {
         for (const id of evicted) {
             await this._removeVectorBestEffort({ scope, id });
+            await this._removeFragmentsBestEffort({ scope, id });
         }
     }
     /**
@@ -476,7 +533,7 @@ export class FileTreeMemoryStore {
             result = fail(`${label} threw: ${String(err)}`);
         }
         if (result.isFailure()) {
-            this._warnSwallowed(`memory: ${label} failed (best-effort; vector index left for rebuild): ${result.message}`);
+            this._warnSwallowed(`memory: ${label} failed (best-effort; derived index left for rebuild): ${result.message}`);
         }
         return result;
     }
@@ -563,6 +620,7 @@ export class FileTreeMemoryStore {
                 .onSuccess(() => this._index.patch('delete', { scope, record: existing }))
                 .thenOnSuccess(async () => {
                 await this._removeVectorBestEffort({ scope, id: existing.envelope.id });
+                await this._removeFragmentsBestEffort({ scope, id: existing.envelope.id });
                 return succeed(existing.envelope.id);
             });
         });
@@ -649,6 +707,7 @@ export class FileTreeMemoryStore {
                     .thenOnSuccess((versionStem) => this._buildVersionedRecord(record, body, current, policy, hash, versionStem, validAt, now, seq)
                     .onSuccess((built) => succeed(this._stampRank(built)))
                     .thenOnSuccess((built) => this._embedOnWrite(built, scope))
+                    .thenOnSuccess((built) => this._embedFragmentsOnWrite(built, scope))
                     .onSuccess((embeddedBuilt) => this._persist(embeddedBuilt, scope, versionStem))
                     .onSuccess((persisted) => this._invalidateCurrents(scope, priorCurrents, validAt, now).onSuccess(() => succeed(persisted)))
                     .onSuccess((persisted) => succeed({ record: persisted, evicted: [] })));
@@ -985,9 +1044,13 @@ export class FileTreeMemoryStore {
     /**
      * Walk the FileTree once and rebuild the index. Also resumes the `seq`
      * counter past the highest persisted `seq` so new writes stay monotonic.
+     *
+     * In `'skip'` mode each per-record failure is captured structurally on
+     * `this._skippedRecords` (path + scope + path-tagged error) at its failure
+     * site and logged at `warn`; the walk keeps every record that loaded.
      */
-    _initialIndex() {
-        return this._collectEntries(this._root, []).onSuccess((entries) => this._index.rebuild(entries).onSuccess(() => {
+    _initialIndex(onRecordError) {
+        return this._collectEntries(this._root, [], onRecordError).onSuccess((entries) => this._index.rebuild(entries).onSuccess(() => {
             for (const entry of entries) {
                 if (entry.record.envelope.seq > this._seq) {
                     this._seq = entry.record.envelope.seq;
@@ -997,11 +1060,11 @@ export class FileTreeMemoryStore {
         }));
     }
     /** Recursively collect every `.md` record under `dir` (scope = path segments). */
-    _collectEntries(dir, scopeSegments) {
+    _collectEntries(dir, scopeSegments, onRecordError) {
         return dir.getChildren().onSuccess((children) => {
             const results = children.map((child) => {
                 if (child.type === 'directory') {
-                    return this._collectEntries(child, [...scopeSegments, child.name]);
+                    return this._collectEntries(child, [...scopeSegments, child.name], onRecordError);
                 }
                 if (!child.name.endsWith(MEMORY_FILE_EXTENSION) || scopeSegments.length === 0) {
                     // Skip non-record files and any record-shaped file sitting at the root
@@ -1009,15 +1072,43 @@ export class FileTreeMemoryStore {
                     return succeed([]);
                 }
                 const scope = scopeSegments.join('/');
-                return child
-                    .getRawContents()
-                    .onSuccess((raw) => parseMemoryFile(raw, this._registry))
-                    .onSuccess((parsedRecord) => this._verifyLoaded(scope, child, parsedRecord))
-                    .onSuccess((verified) => succeed([{ scope, record: verified }]));
+                return this._loadRecordFile(scope, child, onRecordError);
             });
+            // `'skip'` mode: keep every record that parsed, drop the ones that failed
+            // in a single pass (each failure is captured on `this._skippedRecords` and
+            // warn-logged at its site in `_loadRecordFile`). `.orDefault([])` covers
+            // the all-invalid-subtree edge where `mapSuccess` returns Failure because
+            // no element succeeded. `'fail'` mode: `mapResults` fails the whole open on
+            // any bad record — byte-identical to the historical load path.
+            if (onRecordError === 'skip') {
+                return succeed(mapSuccess(results).orDefault([]).flat());
+            }
             return mapResults(results).onSuccess((perChild) => succeed(perChild.flat()));
         });
     }
+    /**
+     * Load and verify one record file. On failure in `'skip'` mode, records the
+     * structured {@link ISkippedRecord} identity (path + scope + path-tagged
+     * error) and logs the skip at `warn`; the failure is still returned so the
+     * caller's `mapSuccess` drops it from the loaded set. In `'fail'` mode the
+     * failure passes through untouched so the historical error is byte-identical.
+     */
+    _loadRecordFile(scope, child, onRecordError) {
+        return child
+            .getRawContents()
+            .onSuccess((raw) => parseMemoryFile(raw, this._registry))
+            .onSuccess((parsedRecord) => this._verifyLoaded(scope, child, parsedRecord))
+            .onSuccess((verified) => succeed([{ scope, record: verified }]))
+            .onFailure((message) => {
+            if (onRecordError === 'skip') {
+                const path = `${scope}/${child.name}`;
+                const error = `memory record '${path}': ${message}`;
+                this._skippedRecords.push({ path, scope, error });
+                this._warnSwallowed(error);
+            }
+            return fail(message);
+        });
+    }
 }
 /**
  * The record-level mutable-field vocabulary: maps a declared mutable field