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

package/temp/ts-agent-memory.api.json

@@ -1814,6 +1814,43 @@
           ],
           "name": "edgeTargetKey"
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@fgv/ts-agent-memory!embeddedFragmentConverter:var",
+          "docComment": "/**\n * Converter for an {@link IEmbeddedFragment}, and the boundary that enforces the fragment-identifiability invariant: **at least one of `locator` / `fragmentId` must be present.**\n *\n * @remarks\n *\n * The invariant lives here rather than in the type. A conditional-required union (`{ locator; fragmentId? } | { locator?; fragmentId }`) was considered and declined: it costs at every construction site and buys nothing at the read site, where each field reads as `… | undefined` either way. What it must not cost is identifiability — a fragment carrying neither identity cannot be resolved back to anything by a consumer holding the query hit, so it is rejected here.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "embeddedFragmentConverter: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Converter",
+              "canonicalReference": "@fgv/ts-utils!Converter:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "IEmbeddedFragment",
+              "canonicalReference": "@fgv/ts-agent-memory!IEmbeddedFragment:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ">"
+            }
+          ],
+          "fileUrlPath": "src/packlets/vector/fragmentConverters.ts",
+          "isReadonly": true,
+          "releaseTag": "Public",
+          "name": "embeddedFragmentConverter",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 5
+          }
+        },
         {
           "kind": "TypeAlias",
           "canonicalReference": "@fgv/ts-agent-memory!EntityId:type",
@@ -1979,7 +2016,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@fgv/ts-agent-memory!FileTreeMemoryStore.create:member(1)",
-              "docComment": "/**\n * 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`).\n */\n",
+              "docComment": "/**\n * 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`).\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -2672,10 +2709,47 @@
             "endIndex": 12
           }
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@fgv/ts-agent-memory!fragmentLocatorConverter:var",
+          "docComment": "/**\n * Converter for an {@link IFragmentLocator}. Validates the two offsets only — the span's *meaning* (character / byte / token unit) is the consumer's, and the index never interprets it. Note the span is advisory: see {@link IFragmentLocator}.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "fragmentLocatorConverter: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Converter",
+              "canonicalReference": "@fgv/ts-utils!Converter:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "IFragmentLocator",
+              "canonicalReference": "@fgv/ts-agent-memory!IFragmentLocator:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ">"
+            }
+          ],
+          "fileUrlPath": "src/packlets/vector/fragmentConverters.ts",
+          "isReadonly": true,
+          "releaseTag": "Public",
+          "name": "fragmentLocatorConverter",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 5
+          }
+        },
         {
           "kind": "Class",
           "canonicalReference": "@fgv/ts-agent-memory!FragmentSemanticRetriever:class",
-          "docComment": "/**\n * 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.\n *\n * @remarks\n *\n * 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.\n *\n * 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`.\n *\n * @public\n */\n",
+          "docComment": "/**\n * 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 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.\n *\n * @remarks\n *\n * Deliberately NOT an {@link IMemoryRetriever}: memory recall is record-granular and 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.\n *\n * 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`.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -4641,7 +4715,7 @@
         {
           "kind": "Interface",
           "canonicalReference": "@fgv/ts-agent-memory!IEmbeddedFragment:interface",
-          "docComment": "/**\n * 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}.\n *\n * @public\n */\n",
+          "docComment": "/**\n * One embedded fragment of a record: the fragment's vector, plus at least one of the two ways to identify it — its advisory in-record {@link IFragmentLocator | span} and/or an opaque consumer-minted {@link IEmbeddedFragment.fragmentId | fragmentId}. Produced by a {@link FragmentEmbedder} and stored via {@link IFragmentVectorIndex.addFragments}.\n *\n * @remarks\n *\n * Both identity fields are optional **in the type**, but the \"at least one\" requirement is real — a fragment carrying neither is unidentifiable at the read side. It is enforced by {@link embeddedFragmentConverter} (and re-checked by the in-package index implementations) rather than by a conditional-required union (`{ locator; fragmentId? } | { locator?; fragmentId }`), which was considered and declined: the union costs at every construction site and buys nothing at the read site, where each field reads as `… | undefined` either way.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -4653,14 +4727,41 @@
           "name": "IEmbeddedFragment",
           "preserveMemberOrder": false,
           "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@fgv/ts-agent-memory!IEmbeddedFragment#fragmentId:member",
+              "docComment": "/**\n * An opaque, consumer-minted identity for this fragment, carried verbatim through the index and returned on the corresponding {@link IVectorQueryHit}. The index **never parses it, never filters on it, and never assigns meaning to it** — it is a bytestring, not part of the query path. It exists so a fragment stays identifiable when its text is not re-derivable from the record body.\n *\n * The guarantee is \"we never parse it\", NOT \"we keep it stable\". Because `addFragments` is whole-record-replace, an updated record re-emits its entire fragment set, so **any stability of a fragment id across re-embeds is the consumer's responsibility**, not the index's.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly fragmentId?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "fragmentId",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@fgv/ts-agent-memory!IEmbeddedFragment#locator:member",
-              "docComment": "/**\n * The fragment's in-record span.\n */\n",
+              "docComment": "/**\n * The region of the record body this fragment was derived from, when one can be stated honestly. Advisory — see {@link IFragmentLocator}; it is NOT a slice that reproduces the fragment text. Omit it for a fragment with no honest body span (a rewriting segmenter), in which case `fragmentId` must be supplied.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "readonly locator: "
+                  "text": "readonly locator?: "
                 },
                 {
                   "kind": "Reference",
@@ -4673,7 +4774,7 @@
                 }
               ],
               "isReadonly": true,
-              "isOptional": false,
+              "isOptional": true,
               "releaseTag": "Public",
               "name": "locator",
               "propertyTypeTokenRange": {
@@ -4684,7 +4785,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@fgv/ts-agent-memory!IEmbeddedFragment#vector:member",
-              "docComment": "/**\n * The embedding vector for that span.\n */\n",
+              "docComment": "/**\n * The embedding vector for this fragment.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -5251,6 +5352,34 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@fgv/ts-agent-memory!IFileTreeMemoryStoreCreateParams#index:member",
+              "docComment": "/**\n * Optional derived-index implementation. Defaults to a fresh {@link MemoryIndex} — omitting this parameter is byte-identical to the store's behavior before the parameter existed. When supplied, the store uses it for EVERY index operation it performs and never holds a second index, so an injected index is the store's only view of its own records:\n *\n * - `rebuild` — once, from the initial vault walk in `create()`. - `patch` — on every persisted write, delete, version invalidation, and cap-cull eviction. - `entries` — behind {@link IMemoryStore.list | list} / {@link IMemoryStore.listScoped | listScoped}, the keyed temporal reads, the write path's content-hash dedup and write-policy admission cohort, AND the temporal (versioned) write and delete paths, which resolve an entity's version history entirely from the index.\n *\n * That last group is the one to weigh before injecting anything other than a pass-through decorator: an index that filters, reorders, or otherwise reshapes `entries()` changes WRITE semantics, not just what reads return. Concretely, on a versioned kind the store derives an entity's whole version history from `entries()` filtered by scope, and that derivation decides which version a `put` treats as current (so what it dedups against and what it merges its patch over), which prior versions it stamps `invalid_at` on, what the admission cohort is, and which versions a `delete` tombstones. An index that hides a version makes it invisible to all of those — the FileTree still holds it, but the store will not supersede, invalidate, or tombstone it. On flat kinds the same reshaping changes what dedups and what a cap-cull policy evicts. A faithful delegating decorator — the intended use below — has no such effect. Note the store's keyed reads ({@link IMemoryStore.get | get} on a flat kind, and {@link IMemoryStore.getById | getById}) go to the FileTree, not the index; the FileTree remains the source of truth and the index stays a derived view.\n *\n * @remarks\n *\n * **This is an instrumentation seam, NOT a resident-memory fix.** The intended use is wrapping the shipped {@link MemoryIndex} in a decorator that counts and times the calls the store makes — resident bytes by kind, open cost against vault size, where the curve actually bends — so a decision about a partial-read redesign can be driven by measurements instead of estimates.\n *\n * It does NOT lower the store's resident-memory ceiling, and injecting a \"persisted\" or \"lazy\" index will not change that. {@link IMemoryIndex}'s read surface returns whole records by construction: `entries()` yields {@link IIndexedMemoryRecord}s and `byKind` / `byTag` / `byRecency` / `byRank` yield `IMemoryRecord<unknown>` — `{ envelope, body }` pairs with the body materialized. Any implementation satisfying the current contract must therefore be able to produce every body on demand. An injected index changes WHERE records come from; it does not change WHETHER bodies are held. Lowering the ceiling requires a partial-read (id-or-envelope-only) redesign of `IMemoryIndex` itself, which is separate, breaking, design-first work and is deliberately not part of this seam.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly index?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "IMemoryIndex",
+                  "canonicalReference": "@fgv/ts-agent-memory!IMemoryIndex:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "index",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@fgv/ts-agent-memory!IFileTreeMemoryStoreCreateParams#logger:member",
@@ -5583,7 +5712,7 @@
         {
           "kind": "Interface",
           "canonicalReference": "@fgv/ts-agent-memory!IFragmentLocator:interface",
-          "docComment": "/**\n * 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.\n *\n * @public\n */\n",
+          "docComment": "/**\n * A half-open `[start, end)` span into a record's body — the in-record locator a {@link IFragmentVectorIndex} may carry on a fragment. `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.\n *\n * @remarks\n *\n * **The span is advisory.** It names the region of the body a fragment was *derived from*; it is NOT a slice guaranteed to reproduce the fragment's text. `body.slice(start, end)` round-trips only under a segmenter that merely chooses boundaries. Under a **rewriting** segmenter — one that turns a span into a curated block, an increasingly common ingestion shape when a model both selects and rewrites — the fragment text is not a substring of the body at all, and the fragmentation is not re-derivable from the body. Treat the span as a pointer for locating context, never as an extraction recipe.\n *\n * A fragment whose provenance cannot honestly be expressed as a body span should omit the locator entirely and carry an {@link IEmbeddedFragment.fragmentId} instead.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -5873,7 +6002,7 @@
         {
           "kind": "Interface",
           "canonicalReference": "@fgv/ts-agent-memory!IFragmentVectorIndex:interface",
-          "docComment": "/**\n * 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.\n *\n * @remarks\n *\n * 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.\n *\n * @public\n */\n",
+          "docComment": "/**\n * The fragment-granular sibling of {@link IVectorIndex}: instead of one vector per record it holds many vectors per record, each tagged with the identity its {@link IEmbeddedFragment} carried, and its `query` returns per-fragment hits carrying that identity back. This is the seam behind sub-document semantic search — the \"discovery\" half of a search-then-read contract, where a hit tells the consumer which record AND which fragment of it to read.\n *\n * @remarks\n *\n * Deliberately NOT `extends IVectorIndex`: an index holding many vectors per record has no well-defined single-vector `add(target, vector)`. It is a parallel contract with three operations — `addFragments`, `remove`, `query` — reusing {@link IVectorQueryHit}, on which both `locator` and `fragmentId` are optional. A fragment hit populates whichever of the two its stored fragment carried; see {@link IVectorQueryHit} for why that is not a discriminator and why fragment-ness is determined by the index queried, not by field presence. Kept distinct from the record-granular index per the consumer contract: memory recall stays record-granular; sub-document knowledge uses a separate fragment index.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -5978,7 +6107,7 @@
             {
               "kind": "MethodSignature",
               "canonicalReference": "@fgv/ts-agent-memory!IFragmentVectorIndex#query:member(1)",
-              "docComment": "/**\n * 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.\n */\n",
+              "docComment": "/**\n * Return the `topK` nearest fragments to `vector`, in descending score order, each hit carrying its record `target` plus whichever of `locator` / `fragmentId` the stored fragment was added with. 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.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -7050,7 +7179,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@fgv/ts-agent-memory!IMemoryCapCullPolicyParams#mutableFields:member",
-              "docComment": "/**\n * The fields a merge-patch update may touch (drawn from the record-level mutable vocabulary: `body` / `tags` / `links` / `provenance` / `embeddingRef`). Fields outside this list are immutable.\n */\n",
+              "docComment": "/**\n * The fields a merge-patch update may touch (drawn from the record-level mutable vocabulary: `body` / `tags` / `links` / `provenance` / `embeddingRef`). Fields outside this list are immutable.\n *\n * @remarks\n *\n * This list — unlike {@link KnowledgeLwwPolicy}'s pinned surface — is caller-supplied, so it is what decides which fields get the RFC-7386 guarantees documented on {@link IWritePolicy.applyUpdate}. Declare `provenance` here to get per-key provenance merging and `null` sub-key clearing; omit it and every provenance patch key is inert (dropped before the merge, so the existing value is preserved verbatim and even a whole-block `null` is a silent no-op rather than an error).\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -11962,7 +12091,7 @@
         {
           "kind": "Class",
           "canonicalReference": "@fgv/ts-agent-memory!InMemoryFragmentCosineIndex:class",
-          "docComment": "/**\n * The brute-force, in-memory cosine {@link IFragmentVectorIndex} — the fragment-granular sibling of {@link InMemoryCosineIndex}. Stores many `Float32Array`s per record (one per in-record {@link IFragmentLocator | span}) and answers a query by computing cosine similarity against every stored fragment, returning the top-k fragment hits by descending score.\n *\n * @remarks\n *\n * Same regime and same non-goals as {@link InMemoryCosineIndex}: no external dependency, no ANN structure, a linear scan over the stored fragments — the seam ({@link IFragmentVectorIndex}) stays open for a consumer to swap a persistent / ANN backend once N grows. `addFragments` is whole-record-replace, so re-authoring a document never leaves stale fragments behind. The index has a single dimension established by the first fragment added; every subsequent fragment and every `query` vector must match it or fail loudly — a mismatched dimension is an embedder-wiring bug, never a silent zero-similarity result. {@link InMemoryFragmentCosineIndex.rebuild | rebuild} clears the index (and the established dimension), so a re-embed with a different model is supported.\n *\n * The optional `maxPerRecord` cap on `query` is applied **during selection**, before the `topK` cut, so one long document with many strong fragments cannot crowd every other record out of the result.\n *\n * @public\n */\n",
+          "docComment": "/**\n * The brute-force, in-memory cosine {@link IFragmentVectorIndex} — the fragment-granular sibling of {@link InMemoryCosineIndex}. Stores many `Float32Array`s per record (one per {@link IEmbeddedFragment | fragment}) and answers a query by computing cosine similarity against every stored fragment, returning the top-k fragment hits by descending score. Each hit carries back whichever of {@link IFragmentLocator | locator} / `fragmentId` its fragment was added with; a fragment must carry at least one of the two.\n *\n * @remarks\n *\n * Same regime and same non-goals as {@link InMemoryCosineIndex}: no external dependency, no ANN structure, a linear scan over the stored fragments — the seam ({@link IFragmentVectorIndex}) stays open for a consumer to swap a persistent / ANN backend once N grows. `addFragments` is whole-record-replace, so re-authoring a document never leaves stale fragments behind. The index has a single dimension established by the first fragment added; every subsequent fragment and every `query` vector must match it or fail loudly — a mismatched dimension is an embedder-wiring bug, never a silent zero-similarity result. {@link InMemoryFragmentCosineIndex.rebuild | rebuild} clears the index (and the established dimension), so a re-embed with a different model is supported.\n *\n * The optional `maxPerRecord` cap on `query` is applied **during selection**, before the `topK` cut, so one long document with many strong fragments cannot crowd every other record out of the result.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -12155,7 +12284,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@fgv/ts-agent-memory!InMemoryFragmentCosineIndex#query:member(1)",
-              "docComment": "/**\n * 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.\n */\n",
+              "docComment": "/**\n * Return the `topK` nearest fragments to `vector`, in descending score order, each hit carrying its record `target` plus whichever of `locator` / `fragmentId` the stored fragment was added with. 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.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -14040,7 +14169,7 @@
         {
           "kind": "Interface",
           "canonicalReference": "@fgv/ts-agent-memory!IVectorQueryHit:interface",
-          "docComment": "/**\n * 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.\n *\n * @remarks\n *\n * The address is a `(scope, id)` pair, NOT a bare {@link MemoryId} — per-scope codecs (e.g. the medium-term codec's `turn-<n>` stems) legally mint the same 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.\n *\n * `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.\n *\n * @public\n */\n",
+          "docComment": "/**\n * 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.\n *\n * @remarks\n *\n * The address is a `(scope, id)` pair, NOT a bare {@link MemoryId} — per-scope codecs (e.g. the medium-term codec's `turn-<n>` stems) legally mint the same 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.\n *\n * **No single field discriminates a fragment hit from a record-granular hit.** A record hit carries neither `locator` nor `fragmentId`; a fragment hit carries at least one of the two, but not necessarily any particular one — a fragment with a body span but no consumer-minted id, and a fragment with an id but no honest span, are both legal. Testing one field for presence therefore cannot tell you which kind of hit you hold.\n *\n * That \"at least one\" requirement is enforced on the upsert side by {@link embeddedFragmentConverter} — a different boundary from this type — and is deliberately NOT offered here as a discriminator either. A caller keyed off it would be coupled to an invariant this type does not own, and would fail silently if the invariant were ever relaxed.\n *\n * **The robust rule is that fragment-ness is determined by which index produced the hit**: {@link IFragmentVectorIndex.query} returns fragment hits and {@link IVectorIndex.query} returns record hits. The caller chose the index it queried, so it already knows which kind it is holding.\n *\n * Note in particular that an absent `locator` now carries **two** distinct meanings — a record-granular hit, or a fragment with no honest body span (see {@link IFragmentLocator}) — which is precisely why presence-branching is unsafe.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -14052,10 +14181,37 @@
           "name": "IVectorQueryHit",
           "preserveMemberOrder": false,
           "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@fgv/ts-agent-memory!IVectorQueryHit#fragmentId:member",
+              "docComment": "/**\n * The opaque identity the producing fragment was stored with, carried back verbatim. Absent on record-granular hits AND on fragment hits stored without one — see the remarks above; do not branch on its presence.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly fragmentId?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "fragmentId",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@fgv/ts-agent-memory!IVectorQueryHit#locator:member",
-              "docComment": "/**\n * The matched fragment's in-record span; present only for fragment-index hits.\n */\n",
+              "docComment": "/**\n * The advisory in-record span the matched fragment was derived from, when the producing fragment carried one. Absent on record-granular hits AND on fragment hits with no honest span — see the remarks above; do not branch on its presence.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -14250,7 +14406,7 @@
             {
               "kind": "MethodSignature",
               "canonicalReference": "@fgv/ts-agent-memory!IWritePolicy#applyUpdate:member(1)",
-              "docComment": "/**\n * Apply a JSON Merge Patch (RFC-7386) to the mutable fields of an existing record. Called when admission is `accept` AND a record with the same `entityId` already exists (an update, not a first write).\n *\n * @param existing - The current persisted record.\n *\n * @param patch - A partial JSON object in Merge Patch format. `null` deletes the corresponding key; arrays replace wholesale; nested objects deep-merge. Only keys in {@link IWritePolicy.mutableFields} are applied.\n *\n * @returns The updated record (envelope + body).\n */\n",
+              "docComment": "/**\n * Apply a JSON Merge Patch (RFC-7386) to the mutable fields of an existing record. Called when admission is `accept` AND a record with the same `entityId` already exists (an update, not a first write).\n *\n * @remarks\n *\n * **RFC-7386 semantics are the contract here, not an artifact of the shipped policies' merge configuration.** Implementations are expected to honor them, and consumers may rely on them:\n *\n * - **Objects merge per key.** A supplied key overwrites; an omitted key is PRESERVED, not dropped. Patching one key of a nested object (e.g. one field of `provenance`) leaves its siblings intact. - **An explicit `null` on a sub-key clears exactly that sub-key.** This is the sanctioned way to remove a single key from a nested object. - **Arrays replace wholesale** — `tags` / `links` are never element-merged. - **A whole-block `null` that would delete a REQUIRED field is rejected loudly** (`Result.fail`), never silently accepted. `body` / `tags` / `links` / `provenance` are required; `embeddingRef` is optional and a `null` restores it to absent (NOT to `null`), so it stays hash-stable.\n *\n * Which fields these guarantees cover is **policy-dependent**: they apply to the fields the policy declares in {@link IWritePolicy.mutableFields}, and a field outside that list is inert — its patch key is dropped before the merge, so a `null` on it neither clears the value nor raises an error.\n *\n * @param existing - The current persisted record.\n *\n * @param patch - A partial JSON object in Merge Patch format. `null` deletes the corresponding key; arrays replace wholesale; nested objects deep-merge. Only keys in {@link IWritePolicy.mutableFields} are applied.\n *\n * @returns The updated record (envelope + body).\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -14766,7 +14922,7 @@
         {
           "kind": "Class",
           "canonicalReference": "@fgv/ts-agent-memory!KnowledgeLwwPolicy:class",
-          "docComment": "/**\n * Last-write-wins write policy for the knowledge kind family. Admission always accepts (no cap, no cull); updates apply an RFC-7386 merge patch restricted to the knowledge mutable surface.\n *\n * @remarks\n *\n * **Merge-surface pin (resolves design-lock §5.3's body-vs-envelope muddle).** The declared `mutableFields` span both axes of a record: `body` is the per-kind body, while `tags` / `links` / `provenance` / `embeddingRef` live on the {@link IMemoryEnvelope}. `applyUpdate` projects exactly those fields — each read from its canonical location — into a single record-level JSON view, runs the merge over that view, then rebuilds a coherent record. The identity and transaction-time envelope fields (`id`, `entityId`, `kind`, `created`, `updated`, `seq`, `contentHash`) are NOT mutable and are preserved verbatim; the store stamps `updated` / `seq` on write.\n *\n * @public\n */\n",
+          "docComment": "/**\n * Last-write-wins write policy for the knowledge kind family. Admission always accepts (no cap, no cull); updates apply an RFC-7386 merge patch restricted to the knowledge mutable surface.\n *\n * @remarks\n *\n * **Merge-surface pin (resolves design-lock §5.3's body-vs-envelope muddle).** The declared `mutableFields` span both axes of a record: `body` is the per-kind body, while `tags` / `links` / `provenance` / `embeddingRef` live on the {@link IMemoryEnvelope}. `applyUpdate` projects exactly those fields — each read from its canonical location — into a single record-level JSON view, runs the merge over that view, then rebuilds a coherent record. The identity and transaction-time envelope fields (`id`, `entityId`, `kind`, `created`, `updated`, `seq`, `contentHash`) are NOT mutable and are preserved verbatim; the store stamps `updated` / `seq` / `contentHash` on write.\n *\n * Because the surface is pinned rather than caller-supplied, the RFC-7386 guarantees documented on {@link IWritePolicy.applyUpdate} apply to every field listed above — in particular to `provenance`, whose keys merge individually, a `null` on any one of which clears that key alone, and a `null` on the whole block of which is rejected loudly (it is a required field). Consumers may depend on this; it is covered by tests.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -14888,7 +15044,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@fgv/ts-agent-memory!KnowledgeLwwPolicy#applyUpdate:member(1)",
-              "docComment": "/**\n * Apply a JSON Merge Patch (RFC-7386) to the mutable fields of an existing record. Called when admission is `accept` AND a record with the same `entityId` already exists (an update, not a first write).\n *\n * @param existing - The current persisted record.\n *\n * @param patch - A partial JSON object in Merge Patch format. `null` deletes the corresponding key; arrays replace wholesale; nested objects deep-merge. Only keys in {@link IWritePolicy.mutableFields} are applied.\n *\n * @returns The updated record (envelope + body).\n */\n",
+              "docComment": "/**\n * Apply a JSON Merge Patch (RFC-7386) to the mutable fields of an existing record. Called when admission is `accept` AND a record with the same `entityId` already exists (an update, not a first write).\n *\n * @remarks\n *\n * **RFC-7386 semantics are the contract here, not an artifact of the shipped policies' merge configuration.** Implementations are expected to honor them, and consumers may rely on them:\n *\n * - **Objects merge per key.** A supplied key overwrites; an omitted key is PRESERVED, not dropped. Patching one key of a nested object (e.g. one field of `provenance`) leaves its siblings intact. - **An explicit `null` on a sub-key clears exactly that sub-key.** This is the sanctioned way to remove a single key from a nested object. - **Arrays replace wholesale** — `tags` / `links` are never element-merged. - **A whole-block `null` that would delete a REQUIRED field is rejected loudly** (`Result.fail`), never silently accepted. `body` / `tags` / `links` / `provenance` are required; `embeddingRef` is optional and a `null` restores it to absent (NOT to `null`), so it stays hash-stable.\n *\n * Which fields these guarantees cover is **policy-dependent**: they apply to the fields the policy declares in {@link IWritePolicy.mutableFields}, and a field outside that list is inert — its patch key is dropped before the merge, so a `null` on it neither clears the value nor raises an error.\n *\n * @param existing - The current persisted record.\n *\n * @param patch - A partial JSON object in Merge Patch format. `null` deletes the corresponding key; arrays replace wholesale; nested objects deep-merge. Only keys in {@link IWritePolicy.mutableFields} are applied.\n *\n * @returns The updated record (envelope + body).\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -15052,7 +15208,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@fgv/ts-agent-memory!KnowledgeLwwPolicy#mutableFields:member",
-              "docComment": "/**\n * The knowledge mutable surface: the body plus the envelope metadata a consumer may revise without minting a new entity.\n */\n",
+              "docComment": "/**\n * The knowledge mutable surface: the body plus the envelope metadata a consumer may revise without minting a new entity. Pinned, not caller-supplied — see the class remarks for what that guarantees.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -15883,7 +16039,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@fgv/ts-agent-memory!MemoryCapCullPolicy#applyUpdate:member(1)",
-              "docComment": "/**\n * Apply a JSON Merge Patch (RFC-7386) to the mutable fields of an existing record. Called when admission is `accept` AND a record with the same `entityId` already exists (an update, not a first write).\n *\n * @param existing - The current persisted record.\n *\n * @param patch - A partial JSON object in Merge Patch format. `null` deletes the corresponding key; arrays replace wholesale; nested objects deep-merge. Only keys in {@link IWritePolicy.mutableFields} are applied.\n *\n * @returns The updated record (envelope + body).\n */\n",
+              "docComment": "/**\n * Apply a JSON Merge Patch (RFC-7386) to the mutable fields of an existing record. Called when admission is `accept` AND a record with the same `entityId` already exists (an update, not a first write).\n *\n * @remarks\n *\n * **RFC-7386 semantics are the contract here, not an artifact of the shipped policies' merge configuration.** Implementations are expected to honor them, and consumers may rely on them:\n *\n * - **Objects merge per key.** A supplied key overwrites; an omitted key is PRESERVED, not dropped. Patching one key of a nested object (e.g. one field of `provenance`) leaves its siblings intact. - **An explicit `null` on a sub-key clears exactly that sub-key.** This is the sanctioned way to remove a single key from a nested object. - **Arrays replace wholesale** — `tags` / `links` are never element-merged. - **A whole-block `null` that would delete a REQUIRED field is rejected loudly** (`Result.fail`), never silently accepted. `body` / `tags` / `links` / `provenance` are required; `embeddingRef` is optional and a `null` restores it to absent (NOT to `null`), so it stays hash-stable.\n *\n * Which fields these guarantees cover is **policy-dependent**: they apply to the fields the policy declares in {@link IWritePolicy.mutableFields}, and a field outside that list is inert — its patch key is dropped before the merge, so a `null` on it neither clears the value nor raises an error.\n *\n * @param existing - The current persisted record.\n *\n * @param patch - A partial JSON object in Merge Patch format. `null` deletes the corresponding key; arrays replace wholesale; nested objects deep-merge. Only keys in {@link IWritePolicy.mutableFields} are applied.\n *\n * @returns The updated record (envelope + body).\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -20567,7 +20723,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@fgv/ts-agent-memory!TemporalVersionedPolicy#applyUpdate:member(1)",
-              "docComment": "/**\n * Apply a JSON Merge Patch (RFC-7386) to the mutable fields of an existing record. Called when admission is `accept` AND a record with the same `entityId` already exists (an update, not a first write).\n *\n * @param existing - The current persisted record.\n *\n * @param patch - A partial JSON object in Merge Patch format. `null` deletes the corresponding key; arrays replace wholesale; nested objects deep-merge. Only keys in {@link IWritePolicy.mutableFields} are applied.\n *\n * @returns The updated record (envelope + body).\n */\n",
+              "docComment": "/**\n * Apply a JSON Merge Patch (RFC-7386) to the mutable fields of an existing record. Called when admission is `accept` AND a record with the same `entityId` already exists (an update, not a first write).\n *\n * @remarks\n *\n * **RFC-7386 semantics are the contract here, not an artifact of the shipped policies' merge configuration.** Implementations are expected to honor them, and consumers may rely on them:\n *\n * - **Objects merge per key.** A supplied key overwrites; an omitted key is PRESERVED, not dropped. Patching one key of a nested object (e.g. one field of `provenance`) leaves its siblings intact. - **An explicit `null` on a sub-key clears exactly that sub-key.** This is the sanctioned way to remove a single key from a nested object. - **Arrays replace wholesale** — `tags` / `links` are never element-merged. - **A whole-block `null` that would delete a REQUIRED field is rejected loudly** (`Result.fail`), never silently accepted. `body` / `tags` / `links` / `provenance` are required; `embeddingRef` is optional and a `null` restores it to absent (NOT to `null`), so it stays hash-stable.\n *\n * Which fields these guarantees cover is **policy-dependent**: they apply to the fields the policy declares in {@link IWritePolicy.mutableFields}, and a field outside that list is inert — its patch key is dropped before the merge, so a `null` on it neither clears the value nor raises an error.\n *\n * @param existing - The current persisted record.\n *\n * @param patch - A partial JSON object in Merge Patch format. `null` deletes the corresponding key; arrays replace wholesale; nested objects deep-merge. Only keys in {@link IWritePolicy.mutableFields} are applied.\n *\n * @returns The updated record (envelope + body).\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",

package/temp/ts-agent-memory.api.md

@@ -102,6 +102,9 @@ export const edgeTargetConverter: Converter<IEdgeTarget>;
 // @public
 export function edgeTargetKey(target: IEdgeTarget): string;
 
+// @public
+export const embeddedFragmentConverter: Converter<IEmbeddedFragment>;
+
 // @public
 export type EntityId = Brand<string, 'EntityId'>;
 
@@ -130,6 +133,9 @@ export const FRAGMENT_SEMANTIC_UNWIRED_MESSAGE: string;
 // @public
 export type FragmentEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<ReadonlyArray<IEmbeddedFragment>>>;
 
+// @public
+export const fragmentLocatorConverter: Converter<IFragmentLocator>;
+
 // @public
 export class FragmentSemanticRetriever {
     get capabilities(): IFragmentRetrieverCapabilities;
@@ -221,7 +227,8 @@ export interface IEdgeTarget {
 
 // @public
 export interface IEmbeddedFragment {
-    readonly locator: IFragmentLocator;
+    readonly fragmentId?: string;
+    readonly locator?: IFragmentLocator;
     readonly vector: Float32Array;
 }
 
@@ -250,6 +257,7 @@ export interface IFileTreeMemoryStoreCreateParams {
     readonly embed?: MemoryEmbedder;
     readonly fragmentEmbedder?: FragmentEmbedder;
     readonly fragmentIndex?: IFragmentVectorIndex;
+    readonly index?: IMemoryIndex;
     readonly logger?: Logging.ILogger;
     readonly observers?: ReadonlyArray<IMemoryObserver>;
     readonly onRecordError?: MemoryRecordErrorMode;
@@ -653,6 +661,7 @@ export interface IVectorIndex {
 
 // @public
 export interface IVectorQueryHit {
+    readonly fragmentId?: string;
     readonly locator?: IFragmentLocator;
     readonly score: number;
     readonly target: IEdgeTarget;