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

package/dist/ts-agent-memory.d.ts

@@ -271,6 +271,22 @@ export declare const edgeTargetConverter: Converter<IEdgeTarget>;
  */
 export declare function edgeTargetKey(target: IEdgeTarget): string;
 
+/**
+ * Converter for an {@link IEmbeddedFragment}, and the boundary that enforces the
+ * fragment-identifiability invariant: **at least one of `locator` / `fragmentId`
+ * must be present.**
+ *
+ * @remarks
+ * 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.
+ * @public
+ */
+export declare const embeddedFragmentConverter: Converter<IEmbeddedFragment>;
+
 /**
  * Consumer-supplied domain key. The stable entity identity across versions;
  * the package never mints identity. Equals {@link MemoryId} for non-temporal
@@ -360,11 +376,19 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      */
     get skippedRecords(): ReadonlyArray<ISkippedRecord>;
     /**
-     * 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: IFileTreeMemoryStoreCreateParams): Result<FileTreeMemoryStore>;
+    /**
+     * 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).
+     */
+    private static _resolveIndex;
     /** {@inheritDoc IMemoryStore.get} */
     get(kind: Kind, entityId: EntityId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
     /** {@inheritDoc IMemoryStore.getById} */
@@ -697,20 +721,31 @@ export declare const FRAGMENT_SEMANTIC_UNWIRED_MESSAGE: string;
  */
 export declare type FragmentEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<ReadonlyArray<IEmbeddedFragment>>>;
 
+/**
+ * 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}.
+ * @public
+ */
+export declare const fragmentLocatorConverter: Converter<IFragmentLocator>;
+
 /**
  * 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
@@ -1016,15 +1051,44 @@ export declare interface IEdgeTarget {
 }
 
 /**
- * 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}.
+ * 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}.
+ *
+ * @remarks
+ * 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.
  * @public
  */
 export declare interface IEmbeddedFragment {
-    /** The fragment's in-record span. */
-    readonly locator: IFragmentLocator;
-    /** The embedding vector for that span. */
+    /**
+     * 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.
+     */
+    readonly locator?: IFragmentLocator;
+    /**
+     * 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.
+     *
+     * 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.
+     */
+    readonly fragmentId?: string;
+    /** The embedding vector for this fragment. */
     readonly vector: Float32Array;
 }
 
@@ -1110,6 +1174,59 @@ export declare interface IFileTreeMemoryStoreCreateParams {
     readonly rankProjectors?: ReadonlyMap<Kind, RankProjector>;
     /** Default codec for kinds without an explicit entry. */
     readonly defaultCodec?: IIdentityCodec;
+    /**
+     * 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:
+     *
+     * - `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.
+     *
+     * 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.
+     *
+     * @remarks
+     * **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.
+     *
+     * 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.
+     */
+    readonly index?: IMemoryIndex;
     /** Scope encoding. Defaults to {@link defaultMemoryScopeEncoding}. */
     readonly scopeEncoding?: (scope: MemoryScopeKey) => Result<string>;
     /**
@@ -1192,10 +1309,24 @@ export declare interface IFileTreeMemoryStoreCreateParams {
 
 /**
  * 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,
+ * {@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.
+ *
+ * @remarks
+ * **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.
+ *
+ * A fragment whose provenance cannot honestly be expressed as a body span should
+ * omit the locator entirely and carry an {@link IEmbeddedFragment.fragmentId}
+ * instead.
  * @public
  */
 export declare interface IFragmentLocator {
@@ -1247,18 +1378,21 @@ export declare interface IFragmentSemanticBackend {
 
 /**
  * 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.
+ * 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.
  *
  * @remarks
- * Deliberately NOT `extends IVectorIndex`: an index keyed by `(target, locator)`
- * has no well-defined single-vector `add(target, vector)`. It is a parallel
- * contract with three operations — `addFragments`, `remove`, `query` — reusing
- * {@link IVectorQueryHit} (whose `locator` is always populated here). Kept distinct
- * from the record-granular index per the consumer contract: memory recall stays
+ * 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.
  * @public
  */
@@ -1277,7 +1411,8 @@ export declare interface IFragmentVectorIndex {
     remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
     /**
      * Return the `topK` nearest fragments to `vector`, in descending score order,
-     * each hit carrying its record `target` and fragment `locator`. When
+     * 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.
@@ -1441,6 +1576,15 @@ export declare interface IMemoryCapCullPolicyParams {
      * 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.
+     *
+     * @remarks
+     * 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).
      */
     readonly mutableFields: ReadonlyArray<string>;
 }
@@ -2122,9 +2266,11 @@ export declare class InMemoryCosineIndex implements IVectorIndex {
 /**
  * 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.
+ * `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.
  *
  * @remarks
  * Same regime and same non-goals as {@link InMemoryCosineIndex}: no external
@@ -2452,9 +2598,27 @@ export declare interface IVectorIndex {
  * that share a stem. The caller re-resolves the hit against the record index by
  * the same scoped address.
  *
- * `locator` is present only on hits from a {@link IFragmentVectorIndex} — it
- * identifies WHICH fragment of the record matched. Record-granular
- * {@link IVectorIndex} hits omit it.
+ * **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.
+ *
+ * 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.
+ *
+ * **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.
+ *
+ * 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.
  * @public
  */
 export declare interface IVectorQueryHit {
@@ -2462,8 +2626,18 @@ export declare interface IVectorQueryHit {
     readonly target: IEdgeTarget;
     /** Backend similarity score; higher is more similar. */
     readonly score: number;
-    /** The matched fragment's in-record span; present only for fragment-index hits. */
+    /**
+     * 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.
+     */
     readonly locator?: IFragmentLocator;
+    /**
+     * 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.
+     */
+    readonly fragmentId?: string;
 }
 
 /**
@@ -2504,6 +2678,27 @@ export declare interface IWritePolicy {
      * record. Called when admission is `accept` AND a record with the same
      * `entityId` already exists (an update, not a first write).
      *
+     * @remarks
+     * **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:
+     *
+     * - **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.
+     *
+     * 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.
+     *
      * @param existing - The current persisted record.
      * @param patch - A partial JSON object in Merge Patch format. `null`
      * deletes the corresponding key; arrays replace wholesale; nested objects
@@ -2564,13 +2759,21 @@ export declare class KnowledgeIdentityCodec implements IIdentityCodec {
  * 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.
+ * preserved verbatim; the store stamps `updated` / `seq` / `contentHash` on write.
+ *
+ * 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.
  * @public
  */
 export declare class KnowledgeLwwPolicy implements IWritePolicy {
     /**
      * The knowledge mutable surface: the body plus the envelope metadata a
-     * consumer may revise without minting a new entity.
+     * consumer may revise without minting a new entity. Pinned, not
+     * caller-supplied — see the class remarks for what that guarantees.
      */
     readonly mutableFields: ReadonlyArray<string>;
     /**

package/etc/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;

package/lib/packlets/retrieve/fragmentSemanticRetriever.d.ts

@@ -49,16 +49,19 @@ export interface IFragmentRetrieverCapabilities {
  * 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/lib/packlets/retrieve/fragmentSemanticRetriever.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fragmentSemanticRetriever.d.ts","sourceRoot":"","sources":["../../../src/packlets/retrieve/fragmentSemanticRetriever.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAiB,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,EAAE,MAC+D,CAAC;AAEhH;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,mDAAmD;IACnD,QAAQ,CAAC,aAAa,EAAE,oBAAoB,CAAC;IAC7C,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;CACpC;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,8BAA8B;IAC7C,kFAAkF;IAClF,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,yBAAyB;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAEhE,OAAO;IAIP,mDAAmD;IACnD,IAAW,YAAY,IAAI,8BAA8B,CAExD;IAED,iCAAiC;WACnB,MAAM,CAAC,MAAM,EAAE;QAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,wBAAwB,CAAC;KAC7C,GAAG,MAAM,CAAC,yBAAyB,CAAC;IAIrC;;;OAGG;IACU,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC;IAoB7F;;;;OAIG;mBACkB,YAAY;CAOlC"}
+{"version":3,"file":"fragmentSemanticRetriever.d.ts","sourceRoot":"","sources":["../../../src/packlets/retrieve/fragmentSemanticRetriever.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAiB,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,EAAE,MAC+D,CAAC;AAEhH;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,mDAAmD;IACnD,QAAQ,CAAC,aAAa,EAAE,oBAAoB,CAAC;IAC7C,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;CACpC;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,8BAA8B;IAC7C,kFAAkF;IAClF,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,yBAAyB;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAEhE,OAAO;IAIP,mDAAmD;IACnD,IAAW,YAAY,IAAI,8BAA8B,CAExD;IAED,iCAAiC;WACnB,MAAM,CAAC,MAAM,EAAE;QAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,wBAAwB,CAAC;KAC7C,GAAG,MAAM,CAAC,yBAAyB,CAAC;IAIrC;;;OAGG;IACU,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC;IAoB7F;;;;OAIG;mBACkB,YAAY;CAOlC"}

package/lib/packlets/retrieve/fragmentSemanticRetriever.js

@@ -17,16 +17,19 @@ exports.FRAGMENT_SEMANTIC_UNWIRED_MESSAGE = 'fragment recall: no fragment index
  * 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/lib/packlets/retrieve/fragmentSemanticRetriever.js.map

@@ -1 +1 @@
-{"version":3,"file":"fragmentSemanticRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/fragmentSemanticRetriever.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,4CAAsD;AAItD;;;;;GAKG;AACU,QAAA,iCAAiC,GAC5C,6GAA6G,CAAC;AA0ChH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAa,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,IAAA,kBAAO,EAAC,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,IAAA,eAAI,EAAC,yCAAiC,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,IAAA,eAAI,EAAC,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,IAAA,eAAI,EAAC,oBAAoB,KAAK,YAAY,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;CACF;AAvDD,8DAuDC","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,4CAAsD;AAItD;;;;;GAKG;AACU,QAAA,iCAAiC,GAC5C,6GAA6G,CAAC;AA0ChH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAa,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,IAAA,kBAAO,EAAC,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,IAAA,eAAI,EAAC,yCAAiC,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,IAAA,eAAI,EAAC,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,IAAA,eAAI,EAAC,oBAAoB,KAAK,YAAY,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;CACF;AAvDD,8DAuDC","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/lib/packlets/store/fileTreeMemoryStore.d.ts

@@ -2,6 +2,7 @@ import { Logging, Result } from '@fgv/ts-utils';
 import { FileTree } from '@fgv/ts-json-base';
 import { EntityId, IIdentityCodec, IMemoryRecord, IWritePolicy, Kind, MemoryId, MemoryScopeKey, RankProjector, Tag } from '../types';
 import { IBodyConverterRegistry as IRegistry } from '../converters';
+import { IMemoryIndex } from '../index';
 import { IMemoryObserver } from '../observe';
 import { FragmentEmbedder, IFragmentVectorIndex, IMemoryRecordSource, IScopedMemoryRecord, IVectorIndex, MemoryEmbedder } from '../vector';
 /**
@@ -137,6 +138,59 @@ export interface IFileTreeMemoryStoreCreateParams {
     readonly rankProjectors?: ReadonlyMap<Kind, RankProjector>;
     /** Default codec for kinds without an explicit entry. */
     readonly defaultCodec?: IIdentityCodec;
+    /**
+     * 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:
+     *
+     * - `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.
+     *
+     * 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.
+     *
+     * @remarks
+     * **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.
+     *
+     * 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.
+     */
+    readonly index?: IMemoryIndex;
     /** Scope encoding. Defaults to {@link defaultMemoryScopeEncoding}. */
     readonly scopeEncoding?: (scope: MemoryScopeKey) => Result<string>;
     /**
@@ -283,11 +337,19 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      */
     get skippedRecords(): ReadonlyArray<ISkippedRecord>;
     /**
-     * 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: IFileTreeMemoryStoreCreateParams): Result<FileTreeMemoryStore>;
+    /**
+     * 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).
+     */
+    private static _resolveIndex;
     /** {@inheritDoc IMemoryStore.get} */
     get(kind: Kind, entityId: EntityId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
     /** {@inheritDoc IMemoryStore.getById} */