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

package/.rush/temp/{bc5b0f2098f7df2a5c498ea77b0de13316349b96.tar.log → 6e1299d1cebb080772163a532c221cd181b54f9f.tar.log}

@@ -1,5 +1,5 @@
-Start time: Tue Jul 28 2026 04:22:12 GMT+0000 (Coordinated Universal Time)
-Invoking "/usr/bin/tar -c -f /home/runner/work/fgv/fgv/common/temp/build-cache/bc5b0f2098f7df2a5c498ea77b0de13316349b96-673fc6539337f6a1.temp -z --files-from=-"
+Start time: Sat Aug 01 2026 02:41:15 GMT+0000 (Coordinated Universal Time)
+Invoking "/usr/bin/tar -c -f /home/runner/work/fgv/fgv/common/temp/build-cache/6e1299d1cebb080772163a532c221cd181b54f9f-dad54f1e2d176bf4.temp -z --files-from=-"
 
 ======= BEGIN PROCESS INPUT ======
 .rush/temp/operation/build/all.log
@@ -77,6 +77,8 @@ dist/packlets/types/temporal.js
 dist/packlets/types/temporal.js.map
 dist/packlets/types/writePolicy.js
 dist/packlets/types/writePolicy.js.map
+dist/packlets/vector/fragmentConverters.js
+dist/packlets/vector/fragmentConverters.js.map
 dist/packlets/vector/inMemoryCosineIndex.js
 dist/packlets/vector/inMemoryCosineIndex.js.map
 dist/packlets/vector/inMemoryFragmentCosineIndex.js
@@ -117,6 +119,8 @@ 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/indexInjection.test.js
+dist/test/unit/store/indexInjection.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
@@ -141,6 +145,8 @@ dist/test/unit/types/temporalPolicy.test.js
 dist/test/unit/types/temporalPolicy.test.js.map
 dist/test/unit/types/writePolicy.test.js
 dist/test/unit/types/writePolicy.test.js.map
+dist/test/unit/vector/fragmentConverters.test.js
+dist/test/unit/vector/fragmentConverters.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
@@ -293,6 +299,10 @@ lib/packlets/types/writePolicy.d.ts
 lib/packlets/types/writePolicy.d.ts.map
 lib/packlets/types/writePolicy.js
 lib/packlets/types/writePolicy.js.map
+lib/packlets/vector/fragmentConverters.d.ts
+lib/packlets/vector/fragmentConverters.d.ts.map
+lib/packlets/vector/fragmentConverters.js
+lib/packlets/vector/fragmentConverters.js.map
 lib/packlets/vector/inMemoryCosineIndex.d.ts
 lib/packlets/vector/inMemoryCosineIndex.d.ts.map
 lib/packlets/vector/inMemoryCosineIndex.js
@@ -373,6 +383,10 @@ 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/indexInjection.test.d.ts
+lib/test/unit/store/indexInjection.test.d.ts.map
+lib/test/unit/store/indexInjection.test.js
+lib/test/unit/store/indexInjection.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
@@ -421,6 +435,10 @@ lib/test/unit/types/writePolicy.test.d.ts
 lib/test/unit/types/writePolicy.test.d.ts.map
 lib/test/unit/types/writePolicy.test.js
 lib/test/unit/types/writePolicy.test.js.map
+lib/test/unit/vector/fragmentConverters.test.d.ts
+lib/test/unit/vector/fragmentConverters.test.d.ts.map
+lib/test/unit/vector/fragmentConverters.test.js
+lib/test/unit/vector/fragmentConverters.test.js.map
 lib/test/unit/vector/inMemoryCosineIndex.test.d.ts
 lib/test/unit/vector/inMemoryCosineIndex.test.d.ts.map
 lib/test/unit/vector/inMemoryCosineIndex.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 (21.343s) ---- \n"}
-{"kind":"O","text":"-------------------- Finished (21.348s) --------------------\n"}
+{"kind":"O","text":" ---- build finished (28.708s) ---- \n"}
+{"kind":"O","text":"-------------------- Finished (28.714s) --------------------\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 (21.343s) ---- 
--------------------- Finished (21.348s) --------------------
+ ---- build finished (28.708s) ---- 
+-------------------- Finished (28.714s) --------------------

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 (21.343s) ---- \n"}
-{"kind":"O","text":"-------------------- Finished (21.348s) --------------------\n"}
+{"kind":"O","text":" ---- build finished (28.708s) ---- \n"}
+{"kind":"O","text":"-------------------- Finished (28.714s) --------------------\n"}

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

@@ -1,3 +1,3 @@
 {
-  "nonCachedDurationMs": 22097.002042000007
+  "nonCachedDurationMs": 29559.986292
 }

package/README.md

@@ -6,11 +6,12 @@ edges, content-hash dedup, and the optional-layer seams (vector / temporal /
 observe). It owns none of a consumer's processing, transformation, or
 composition logic.
 
-> **Status:** v0.1, under active development. The package is being built
-> knowledge-first. This tier (B0) ships the foundational type model and
-> converters only — no store, index, retrieval, observe, or vector code yet.
+> **Status:** under active development. The package is being built
+> knowledge-first. The surface listing below covers the foundational type model
+> and converters; the store, index, retrieval, observe, and vector layers ship
+> alongside them and are not itemized here.
 
-## B0 surface (this tier)
+## Foundational surface
 
 ### `types` packlet
 
@@ -34,6 +35,80 @@ composition logic.
   `joinFrontmatter` / `parseMemoryFile` / `serializeMemoryFile` helpers for
   the `---\n<yaml>\n---\n<body>` memory-file format.
 
+## Record updates — the merge contract
+
+When a `put` targets an `entityId` that already exists, the write is an
+**update**, not a replace. The store projects the incoming record's mutable
+fields into a patch and hands it to the kind's `IWritePolicy.applyUpdate`, which
+applies it as an **RFC-7386 JSON Merge Patch** over the policy's declared
+mutable surface. This is a **pinned contract**, not an artifact of the current
+merge configuration — the shipped policies compose `@fgv/ts-json`'s `JsonEditor`
+with `{ nullAsDelete: true, arrayMergeBehavior: 'replace' }` specifically to get
+RFC-7386 semantics, and `applyUpdate` documents them as the interface contract.
+
+Within the policy's declared mutable surface:
+
+- **Objects merge per key.** Keys you supply overwrite; keys you omit are
+  **preserved**, not dropped. An update that sets one provenance field leaves
+  every sibling field intact.
+- **An explicit `null` on a sub-key clears that sub-key.** This is the
+  sanctioned way to remove a single key from a nested object such as
+  `provenance`. The cleared key is gone from the persisted record and does not
+  reappear on reload.
+- **Arrays replace wholesale.** `tags` and `links` are not element-merged.
+- **A whole-block `null` on a required field is rejected loudly**, never
+  silently accepted. `body`, `tags`, `links`, and `provenance` are required; a
+  patch that deletes one fails with
+  `... merge patch may not delete required field(s): <names>`. (`embeddingRef`
+  is optional and *may* be cleared by a `null`, which restores it to absent
+  rather than to `null`.)
+- **Keys outside the mutable surface are ignored.** Identity and
+  transaction-time envelope fields (`id`, `entityId`, `kind`, `created`,
+  `updated`, `seq`, `contentHash`) are preserved verbatim; the store stamps
+  `updated` / `seq` / `contentHash` on write.
+
+### `provenance` is on the pinned surface
+
+`KnowledgeLwwPolicy` and `TemporalVersionedPolicy` both hard-code their mutable
+surface as `['body', 'tags', 'links', 'provenance', 'embeddingRef']`. For those
+policies the guarantees above apply to `provenance` specifically: per-key merge,
+sub-key clearing via `null`, and loud rejection of a whole-block delete are all
+part of the contract and are pinned by tests.
+
+```ts
+// existing.envelope.provenance: { source: 'agent', confidence: 0.9, note: 'stale' }
+
+// clear one sub-key; siblings survive
+policy.applyUpdate(existing, { provenance: { note: null } });
+// => provenance: { source: 'agent', confidence: 0.9 }
+
+// revise one sub-key; siblings survive
+policy.applyUpdate(existing, { provenance: { confidence: 0.5 } });
+// => provenance: { source: 'agent', confidence: 0.5, note: 'stale' }
+
+// delete the whole block — rejected, not silently accepted
+policy.applyUpdate(existing, { provenance: null });
+// => Result.fail('knowledge LWW: merge patch may not delete required field(s): provenance')
+```
+
+Going through the store rather than calling a policy directly, the same three
+cases are expressed as the `provenance` value on the record you `put`: include a
+key to set it, set a key to `null` to clear it, and omit a key to leave it
+alone. A whole-block delete is not expressible there at all —
+`IMemoryEnvelope.provenance` is non-nullable and `envelopeConverter` rejects
+`null` — so that case fails at the converter instead of at the policy. Either
+way it fails loudly.
+
+### The surface is policy-dependent
+
+`MemoryCapCullPolicy` takes its `mutableFields` from the caller, so **what it
+guarantees depends on what you declared**. A field you did not declare mutable
+is not merged at all: patch keys naming it are dropped before the merge runs, so
+a `null` on it neither clears anything nor raises an error — it is simply inert,
+and the existing value is preserved verbatim. If you want the guarantees above
+for `provenance` under a cap-cull policy, `provenance` must appear in the
+`mutableFields` you pass to `MemoryCapCullPolicy.create`.
+
 ## Conventions
 
 `Result<T>` on every fallible operation; no `any`; Converters/Validators for

package/dist/packlets/retrieve/fragmentSemanticRetriever.js

@@ -14,16 +14,19 @@ export const FRAGMENT_SEMANTIC_UNWIRED_MESSAGE = 'fragment recall: no fragment i
  * 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.
+ * {@link IVectorQueryHit | hits} (each carrying a record `target` AND whichever of
+ * `locator` / `fragmentId` the stored fragment was indexed with), NOT resolved
+ * records: the consumer re-reads each record and resolves the fragment on its own
+ * read side. Note the `locator` span is advisory — see {@link IFragmentLocator}; it
+ * is not a slice guaranteed to reproduce the fragment's text.
  *
  * @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.
+ * returns records; fragment discovery is fragment-granular and returns fragment
+ * identities. 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 identity fields that
+ * only make sense here.
  *
  * When no backend is wired, `supportsFragmentRecall` is `false` and any fragment
  * query degrades loudly ({@link FRAGMENT_SEMANTIC_UNWIRED_MESSAGE}) — it NEVER

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

@@ -1 +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"]}
+{"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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;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 whichever of\n * `locator` / `fragmentId` the stored fragment was indexed with), NOT resolved\n * records: the consumer re-reads each record and resolves the fragment on its own\n * read side. Note the `locator` span is advisory — see {@link IFragmentLocator}; it\n * is not a slice guaranteed to reproduce the fragment's text.\n *\n * @remarks\n * Deliberately NOT an {@link IMemoryRetriever}: memory recall is record-granular and\n * returns records; fragment discovery is fragment-granular and returns fragment\n * identities. Keeping it a distinct surface matches the consumer contract (memory\n * stays record-granular; sub-document knowledge uses a separate fragment index) and\n * avoids overloading the record retriever's return type with identity fields that\n * only make 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/store/fileTreeMemoryStore.js

@@ -60,12 +60,14 @@ export class FileTreeMemoryStore {
         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
-     * indexed (and the `seq` counter resumes past the highest persisted `seq`).
+     * Family-convention factory. Resolves the derived index (the caller's
+     * {@link IFileTreeMemoryStoreCreateParams.index | index} when supplied, a fresh
+     * {@link MemoryIndex} otherwise) and a default LWW policy, then performs an
+     * initial FileTree walk so an existing vault is indexed (and the `seq` counter
+     * resumes past the highest persisted `seq`).
      */
     static create(params) {
-        return KnowledgeLwwPolicy.create().onSuccess((defaultPolicy) => MemoryIndex.create().onSuccess((index) => {
+        return KnowledgeLwwPolicy.create().onSuccess((defaultPolicy) => FileTreeMemoryStore._resolveIndex(params.index).onSuccess((index) => {
             var _a, _b, _c, _d, _e, _f, _g, _h;
             const store = new FileTreeMemoryStore({
                 root: params.root,
@@ -88,6 +90,20 @@ export class FileTreeMemoryStore {
             return store._initialIndex((_h = params.onRecordError) !== null && _h !== void 0 ? _h : 'fail').onSuccess(() => succeed(store));
         }));
     }
+    /**
+     * Resolve the derived index for a `create()`: the caller's injected
+     * {@link IMemoryIndex} verbatim, or a fresh {@link MemoryIndex} when none was
+     * supplied (the default that keeps an omitting caller byte-identical).
+     */
+    static _resolveIndex(index) {
+        // Nullish rather than strictly-undefined, matching how every sibling optional
+        // param in `create()` handles absence (`params.codecs ?? new Map()`, and so on).
+        // A JS caller — or a TS caller arriving through an `unknown` escape hatch —
+        // passing `null` otherwise gets `null` installed as the store's index and fails
+        // later inside `entries()` with a message that names neither the param nor the
+        // cause.
+        return index ? succeed(index) : MemoryIndex.create();
+    }
     /** {@inheritDoc IMemoryStore.get} */
     async get(kind, entityId) {
         var _a;