@fgv/ts-agent-memory 5.1.0-50 → 5.1.0-51

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

@@ -445,6 +445,9 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
     listScoped(): Promise<Result<ReadonlyArray<IScopedMemoryRecord>>>;
     /** {@inheritDoc IMemoryRecordResolver.resolveRecord} */
     resolveRecord(scope: MemoryScopeKey, id: MemoryId): Result<IMemoryRecord<unknown> | undefined>;
+    private _codec;
+    /** {@inheritDoc IIdentityResolver.resolveIdentity} */
+    resolveIdentity(kind: Kind, entityId: EntityId): Result<IIdentityCodecResult>;
     /**
      * Materialize a selected set of entries into records, dropping any that have
      * vanished since selection.
@@ -717,7 +720,6 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      * than preserving it), so a ranking bug never loses an authoritative write.
      */
     private _stampRank;
-    private _codecFor;
     private _policyFor;
     /** {@inheritDoc IMemoryStore.dedupScopeFor} */
     dedupScopeFor(kind: Kind): DedupScope;
@@ -777,6 +779,28 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
     private _loadRecordFile;
 }
 
+/**
+ * The message returned when exactly one of `entityId` / `kind` is supplied.
+ *
+ * @remarks
+ * They travel together because `kind` is what selects the identity codec, and the
+ * codec is what makes the resolution unambiguous. One without the other is not a
+ * partial narrowing that could be honored best-effort — it is not a narrowing at all.
+ * @public
+ */
+export declare const FRAGMENT_NARROWING_INCOMPLETE_MESSAGE: string;
+
+/**
+ * The loud-degradation message returned when a query carries a record narrowing but
+ * no {@link IIdentityResolver} is wired to resolve it.
+ *
+ * @remarks
+ * Deliberately a `Failure` rather than a silently-global search: answering a scoped
+ * question with an unscoped result is the failure this narrowing exists to remove.
+ * @public
+ */
+export declare const FRAGMENT_NARROWING_UNRESOLVABLE_MESSAGE: string;
+
 /**
  * The loud-degradation message a {@link FragmentSemanticRetriever} returns when a
  * fragment query is issued but no {@link IFragmentSemanticBackend | backend} is
@@ -829,18 +853,44 @@ export declare const fragmentLocatorConverter: Converter<IFragmentLocator>;
  */
 export declare class FragmentSemanticRetriever {
     private readonly _backend;
+    private readonly _identityResolver;
     private constructor();
     /** What this retriever can do given its wiring. */
     get capabilities(): IFragmentRetrieverCapabilities;
-    /** Family-convention factory. */
+    /**
+     * Family-convention factory.
+     *
+     * @param params - `backend` wires fragment recall itself. `identityResolver`
+     * resolves a query's `(kind, entityId)` narrowing to a storage address;
+     * `IMemoryStore` implements it, so the usual wiring is
+     * `{ backend, identityResolver: store }`. It is optional because an unscoped
+     * fragment search needs nothing to resolve — but a query that *does* carry a
+     * narrowing fails loudly without it rather than quietly searching everything.
+     */
     static create(params: {
         readonly backend?: IFragmentSemanticBackend;
+        readonly identityResolver?: IIdentityResolver;
     }): Result<FragmentSemanticRetriever>;
     /**
      * Embed `query.semantic`, query the fragment index, and return the per-fragment
      * hits in descending score order. Fails loudly when no backend is wired.
      */
     retrieve(query: IFragmentQuery): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    /**
+     * Turn the query's consumer-facing narrowing into the storage-address narrowing
+     * the index understands.
+     *
+     * @remarks
+     * `kind` selects the identity codec and the codec computes the record's storage
+     * address, so this is a deterministic resolution rather than a search —
+     * which is what makes a colliding `entityId` across kinds a non-issue.
+     *
+     * A **versioned** kind resolves to the entity's own subtree scope and deliberately
+     * carries no `id`, so the narrowing covers every version of the entity — including
+     * superseded ones, which are invalidated but never pruned from the index. A
+     * non-versioned kind resolves to exactly one record.
+     */
+    private _resolveOptions;
     /**
      * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`
      * and a thrown/rejected promise into a single `fragment recall: <label> failed`
@@ -1558,6 +1608,85 @@ export declare interface IFragmentQuery {
      * Applied during selection (before the `topK` cut). Omit for uncapped.
      */
     readonly maxPerRecord?: number;
+    /**
+     * Narrow the search to one record's fragments: the consumer-supplied domain key
+     * of the record to search within. **Must be supplied with
+     * {@link IFragmentQuery.kind}.**
+     *
+     * @remarks
+     * The narrowing is applied **during selection, before the `topK` cut**, so the
+     * `topK` you ask for is the `topK` you get. Filtering a global result afterwards
+     * is not equivalent: it truncates to `topK` across every record first, so a scoped
+     * search would come back short whenever other records outscored this one's
+     * fragments.
+     *
+     * For a versioned kind this narrows to **every version of the entity** — literally
+     * every version, superseded ones included, because invalidation stamps `invalid_at`
+     * without pruning that version's fragments. Nothing on a hit distinguishes a
+     * current fragment from a historical one. That matches the record-granular vector
+     * lane; it is not currency filtering.
+     */
+    readonly entityId?: EntityId;
+    /**
+     * The kind of the record named by {@link IFragmentQuery.entityId}. **Must be
+     * supplied with it.**
+     *
+     * @remarks
+     * This is not decoration and not a filter: `kind` **selects the identity codec**,
+     * and the codec computes the storage address. An `EntityId` promises no uniqueness
+     * beyond a scope — the same id under two kinds is the ordinary case, not a
+     * pathological one — so without `kind` the resolution is ambiguous, and with it
+     * ambiguity is structurally impossible.
+     */
+    readonly kind?: Kind;
+}
+
+/**
+ * Selection-time narrowing for {@link IFragmentVectorIndex.query}. Every member is
+ * applied **before** the `topK` cut.
+ *
+ * @remarks
+ * `scope` (optionally with `id`) is the record narrowing. It is expressed as a
+ * storage address rather than as a consumer-facing `(kind, entityId)` because that
+ * is what the index is keyed by; resolving one to the other is
+ * `IIdentityResolver.resolveIdentity`'s job, and doing it above the index keeps the
+ * index dealing only in the keys it actually holds.
+ *
+ * **`scope` alone is not a coarser accident — it is what a versioned kind needs.**
+ * `TemporalIdentityCodec` files every version of an entity in its own per-entity
+ * subtree, so for a versioned kind the entity's subtree *is* the narrowing and
+ * `{ scope }` means "every version of this entity". A non-versioned kind resolves to
+ * a single record and supplies `{ scope, id }`.
+ *
+ * **"Every version" is literal, and includes superseded ones.** Invalidation stamps
+ * `invalid_at` on an envelope; it does not prune that version's fragments from the
+ * index. So a scope-narrowed query returns current and historical fragments alike,
+ * and a hit carries nothing that distinguishes them — `IVectorQueryHit` has no
+ * temporal fields. This is the record-granular vector lane's existing behaviour
+ * rather than something this narrowing introduces, but do not read the subtree
+ * narrowing as currency filtering: it is not, and there is no `asOf` axis here to
+ * make it so.
+ * @public
+ */
+export declare interface IFragmentQueryOptions {
+    /**
+     * Maximum number of fragments any single record may contribute. Omit for
+     * uncapped. With a single-record narrowing (`scope` + `id`) this caps the one
+     * record's contribution, which is a second cap on the same axis rather than a
+     * cross-record fairness knob — usually you want one or the other, not both.
+     */
+    readonly maxPerRecord?: number;
+    /**
+     * Restrict the search to fragments of records in this scope. Omit to search every
+     * record.
+     */
+    readonly scope?: MemoryScopeKey;
+    /**
+     * With {@link IFragmentQueryOptions.scope}, restrict further to the single record
+     * at `(scope, id)`. Ignored — and meaningless — without `scope`, since a bare `id`
+     * does not address a record.
+     */
+    readonly id?: MemoryId;
 }
 
 /**
@@ -1637,12 +1766,16 @@ export declare interface IFragmentVectorIndex {
     /**
      * 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.
+     * `fragmentId` the stored fragment was added with.
+     *
+     * @remarks
+     * **Every member of `options` is applied during selection, before the `topK`
+     * cut.** That ordering is the contract, not an implementation detail: a narrowing
+     * applied afterwards would mean the caller's `topK` is not the `topK` that reached
+     * the index, so a scoped search would be exact only when a global over-fetch
+     * happened to be generous enough. See {@link IFragmentQueryOptions}.
      */
-    query(vector: Float32Array, topK: number, maxPerRecord?: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    query(vector: Float32Array, topK: number, options?: IFragmentQueryOptions): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
     /**
      * Whether this index holds **any** fragment for the scope-qualified `target`.
      *
@@ -1794,6 +1927,45 @@ export declare interface IIdentityCodecResult {
     readonly isVersioned: boolean;
 }
 
+/**
+ * Resolves a consumer-facing `(kind, entityId)` address to the storage address the
+ * vault files it under, **without reading the record**.
+ *
+ * @remarks
+ * This is the resolution `IMemoryStore.get(kind, entityId)` already performs before
+ * it reads anything: `kind` selects the kind's `IIdentityCodec`, and the codec's
+ * `encode` computes `{ scope, idStem, isVersioned }`. Exposing it separately lets a
+ * caller that needs only the *address* — a fragment query narrowing to one record,
+ * say — avoid paying for a read it does not want.
+ *
+ * **The resolution is a function, not a search, and that is the load-bearing
+ * property.** A consumer holds an `EntityId`; a vector hit is addressed by a
+ * `(scope, id)` pair; and `EntityId` promises no uniqueness beyond a scope, so the
+ * same id may legitimately appear in several scopes (a document `acme-corp` under
+ * one kind and the entity `acme-corp` under another is the ordinary case, not a
+ * pathological one). Supplying `kind` selects one codec, and a codec cannot return
+ * two answers — so ambiguity is structurally impossible rather than merely unlikely,
+ * and no disambiguation pass is needed anywhere downstream.
+ *
+ * Narrow by design, mirroring `IMemoryRecordResolver`: a component that needs to
+ * turn an entity address into a storage address should depend on this rather than on
+ * the whole store.
+ * @public
+ */
+export declare interface IIdentityResolver {
+    /**
+     * The storage address `(kind, entityId)` maps to, without reading the record.
+     *
+     * @param kind - Selects the identity codec. Required: it is what makes the
+     * resolution unambiguous.
+     * @param entityId - The consumer-supplied domain key.
+     * @returns `Success` with the codec's `{ scope, idStem, isVersioned }`, or
+     * `Failure` if no codec is registered for `kind` (and no default is wired) or the
+     * codec rejects the id. Both are caller errors and both are loud.
+     */
+    resolveIdentity(kind: Kind, entityId: EntityId): Result<IIdentityCodecResult>;
+}
+
 /**
  * Coverage of the record-granular vector index.
  * @public
@@ -2608,7 +2780,7 @@ export declare interface IMemoryRetrieverCapabilities {
  * a consumer actually holds, not only for the concrete `FileTreeMemoryStore`.
  * @public
  */
-export declare interface IMemoryStore extends IMemoryRecordResolver {
+export declare interface IMemoryStore extends IMemoryRecordResolver, IIdentityResolver {
     /**
      * Keyed read by entity id. Resolves `entityId` to a storage address via the
      * registered {@link IIdentityCodec} for `kind`. Returns `undefined` when no
@@ -3086,7 +3258,18 @@ export declare class InMemoryFragmentCosineIndex implements IFragmentVectorIndex
     /** {@inheritDoc IFragmentVectorIndex.remove} */
     remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
     /** {@inheritDoc IFragmentVectorIndex.query} */
-    query(vector: Float32Array, topK: number, maxPerRecord?: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    query(vector: Float32Array, topK: number, options?: IFragmentQueryOptions): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    /**
+     * The records a query is allowed to score, honoring the `scope` / `id` narrowing.
+     *
+     * @remarks
+     * The single-record case is an O(1) map lookup rather than a scan, because the
+     * record map is keyed by `edgeTargetKey`. The scope-only case (a versioned kind's
+     * per-entity subtree) is a filtered walk — still bounded by the vault, but it
+     * scores only the entity's own fragments, which is what makes the caller's `topK`
+     * meaningful.
+     */
+    private _selectRecords;
     /**
      * Re-embed every record from `source` and rebuild the fragment index from
      * scratch. Clears the current contents (and the established dimension) first, so

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

@@ -1,4 +1,5 @@
 import { Result } from '@fgv/ts-utils';
+import { EntityId, IIdentityResolver, Kind } from '../types';
 import { IFragmentVectorIndex, IVectorQueryHit } from '../vector';
 import { QueryEmbedder } from './semanticRetriever';
 /**
@@ -8,6 +9,26 @@ import { QueryEmbedder } from './semanticRetriever';
  * @public
  */
 export declare const FRAGMENT_SEMANTIC_UNWIRED_MESSAGE: string;
+/**
+ * The loud-degradation message returned when a query carries a record narrowing but
+ * no {@link IIdentityResolver} is wired to resolve it.
+ *
+ * @remarks
+ * Deliberately a `Failure` rather than a silently-global search: answering a scoped
+ * question with an unscoped result is the failure this narrowing exists to remove.
+ * @public
+ */
+export declare const FRAGMENT_NARROWING_UNRESOLVABLE_MESSAGE: string;
+/**
+ * The message returned when exactly one of `entityId` / `kind` is supplied.
+ *
+ * @remarks
+ * They travel together because `kind` is what selects the identity codec, and the
+ * codec is what makes the resolution unambiguous. One without the other is not a
+ * partial narrowing that could be honored best-effort — it is not a narrowing at all.
+ * @public
+ */
+export declare const FRAGMENT_NARROWING_INCOMPLETE_MESSAGE: string;
 /**
  * The fragment backend wired into a {@link FragmentSemanticRetriever}: the fragment
  * index to query and the embedder that turns the query text into a vector. Both are
@@ -36,6 +57,37 @@ export interface IFragmentQuery {
      * Applied during selection (before the `topK` cut). Omit for uncapped.
      */
     readonly maxPerRecord?: number;
+    /**
+     * Narrow the search to one record's fragments: the consumer-supplied domain key
+     * of the record to search within. **Must be supplied with
+     * {@link IFragmentQuery.kind}.**
+     *
+     * @remarks
+     * The narrowing is applied **during selection, before the `topK` cut**, so the
+     * `topK` you ask for is the `topK` you get. Filtering a global result afterwards
+     * is not equivalent: it truncates to `topK` across every record first, so a scoped
+     * search would come back short whenever other records outscored this one's
+     * fragments.
+     *
+     * For a versioned kind this narrows to **every version of the entity** — literally
+     * every version, superseded ones included, because invalidation stamps `invalid_at`
+     * without pruning that version's fragments. Nothing on a hit distinguishes a
+     * current fragment from a historical one. That matches the record-granular vector
+     * lane; it is not currency filtering.
+     */
+    readonly entityId?: EntityId;
+    /**
+     * The kind of the record named by {@link IFragmentQuery.entityId}. **Must be
+     * supplied with it.**
+     *
+     * @remarks
+     * This is not decoration and not a filter: `kind` **selects the identity codec**,
+     * and the codec computes the storage address. An `EntityId` promises no uniqueness
+     * beyond a scope — the same id under two kinds is the ordinary case, not a
+     * pathological one — so without `kind` the resolution is ambiguous, and with it
+     * ambiguity is structurally impossible.
+     */
+    readonly kind?: Kind;
 }
 /**
  * What a {@link FragmentSemanticRetriever} can do given its wiring.
@@ -71,18 +123,44 @@ export interface IFragmentRetrieverCapabilities {
  */
 export declare class FragmentSemanticRetriever {
     private readonly _backend;
+    private readonly _identityResolver;
     private constructor();
     /** What this retriever can do given its wiring. */
     get capabilities(): IFragmentRetrieverCapabilities;
-    /** Family-convention factory. */
+    /**
+     * Family-convention factory.
+     *
+     * @param params - `backend` wires fragment recall itself. `identityResolver`
+     * resolves a query's `(kind, entityId)` narrowing to a storage address;
+     * `IMemoryStore` implements it, so the usual wiring is
+     * `{ backend, identityResolver: store }`. It is optional because an unscoped
+     * fragment search needs nothing to resolve — but a query that *does* carry a
+     * narrowing fails loudly without it rather than quietly searching everything.
+     */
     static create(params: {
         readonly backend?: IFragmentSemanticBackend;
+        readonly identityResolver?: IIdentityResolver;
     }): Result<FragmentSemanticRetriever>;
     /**
      * Embed `query.semantic`, query the fragment index, and return the per-fragment
      * hits in descending score order. Fails loudly when no backend is wired.
      */
     retrieve(query: IFragmentQuery): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    /**
+     * Turn the query's consumer-facing narrowing into the storage-address narrowing
+     * the index understands.
+     *
+     * @remarks
+     * `kind` selects the identity codec and the codec computes the record's storage
+     * address, so this is a deterministic resolution rather than a search —
+     * which is what makes a colliding `entityId` across kinds a non-issue.
+     *
+     * A **versioned** kind resolves to the entity's own subtree scope and deliberately
+     * carries no `id`, so the narrowing covers every version of the entity — including
+     * superseded ones, which are invalidated but never pruned from the index. A
+     * non-versioned kind resolves to exactly one record.
+     */
+    private _resolveOptions;
     /**
      * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`
      * and a thrown/rejected promise into a single `fragment recall: <label> failed`

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;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"fragmentSemanticRetriever.d.ts","sourceRoot":"","sources":["../../../src/packlets/retrieve/fragmentSemanticRetriever.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAgC,MAAM,eAAe,CAAC;AACrE,OAAO,EAAW,QAAQ,EAAwB,iBAAiB,EAAE,IAAI,EAAY,MAAM,UAAU,CAAC;AACtG,OAAO,EAAyB,oBAAoB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACzF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,EAAE,MAC+D,CAAC;AAEhH;;;;;;;;GAQG;AACH,eAAO,MAAM,uCAAuC,EAAE,MAC8E,CAAC;AAErI;;;;;;;;GAQG;AACH,eAAO,MAAM,qCAAqC,EAAE,MACgF,CAAC;AAErI;;;;;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;IAE/B;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAE7B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;CACtB;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;IAChE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAgC;IAElE,OAAO;IAQP,mDAAmD;IACnD,IAAW,YAAY,IAAI,8BAA8B,CAExD;IAED;;;;;;;;;OASG;WACW,MAAM,CAAC,MAAM,EAAE;QAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,wBAAwB,CAAC;QAC5C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;KAC/C,GAAG,MAAM,CAAC,yBAAyB,CAAC;IAIrC;;;OAGG;IACU,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC;IA2B7F;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,eAAe;IAwCvB;;;;OAIG;mBACkB,YAAY;CAOlC"}

package/lib/packlets/retrieve/fragmentSemanticRetriever.js

@@ -4,8 +4,9 @@
  * SPDX-License-Identifier: MIT
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FragmentSemanticRetriever = exports.FRAGMENT_SEMANTIC_UNWIRED_MESSAGE = void 0;
+exports.FragmentSemanticRetriever = exports.FRAGMENT_NARROWING_INCOMPLETE_MESSAGE = exports.FRAGMENT_NARROWING_UNRESOLVABLE_MESSAGE = exports.FRAGMENT_SEMANTIC_UNWIRED_MESSAGE = void 0;
 const ts_utils_1 = require("@fgv/ts-utils");
+const types_1 = require("../types");
 /**
  * The loud-degradation message a {@link FragmentSemanticRetriever} returns when a
  * fragment query is issued but no {@link IFragmentSemanticBackend | backend} is
@@ -13,6 +14,26 @@ const ts_utils_1 = require("@fgv/ts-utils");
  * @public
  */
 exports.FRAGMENT_SEMANTIC_UNWIRED_MESSAGE = 'fragment recall: no fragment index is wired; wire an IFragmentSemanticBackend to enable sub-document search';
+/**
+ * The loud-degradation message returned when a query carries a record narrowing but
+ * no {@link IIdentityResolver} is wired to resolve it.
+ *
+ * @remarks
+ * Deliberately a `Failure` rather than a silently-global search: answering a scoped
+ * question with an unscoped result is the failure this narrowing exists to remove.
+ * @public
+ */
+exports.FRAGMENT_NARROWING_UNRESOLVABLE_MESSAGE = 'fragment recall: a record narrowing was supplied but no identity resolver is wired; pass one to FragmentSemanticRetriever.create';
+/**
+ * The message returned when exactly one of `entityId` / `kind` is supplied.
+ *
+ * @remarks
+ * They travel together because `kind` is what selects the identity codec, and the
+ * codec is what makes the resolution unambiguous. One without the other is not a
+ * partial narrowing that could be honored best-effort — it is not a narrowing at all.
+ * @public
+ */
+exports.FRAGMENT_NARROWING_INCOMPLETE_MESSAGE = 'fragment recall: `entityId` and `kind` must be supplied together — `kind` selects the identity codec that resolves the narrowing';
 /**
  * The sub-document semantic-search retriever — the "discovery" half of a
  * search-then-read contract. It embeds a fragment query, queries the
@@ -38,16 +59,26 @@ exports.FRAGMENT_SEMANTIC_UNWIRED_MESSAGE = 'fragment recall: no fragment index
  * @public
  */
 class FragmentSemanticRetriever {
-    constructor(backend) {
+    constructor(backend, identityResolver) {
         this._backend = backend;
+        this._identityResolver = identityResolver;
     }
     /** What this retriever can do given its wiring. */
     get capabilities() {
         return { supportsFragmentRecall: this._backend !== undefined };
     }
-    /** Family-convention factory. */
+    /**
+     * Family-convention factory.
+     *
+     * @param params - `backend` wires fragment recall itself. `identityResolver`
+     * resolves a query's `(kind, entityId)` narrowing to a storage address;
+     * `IMemoryStore` implements it, so the usual wiring is
+     * `{ backend, identityResolver: store }`. It is optional because an unscoped
+     * fragment search needs nothing to resolve — but a query that *does* carry a
+     * narrowing fails loudly without it rather than quietly searching everything.
+     */
     static create(params) {
-        return (0, ts_utils_1.succeed)(new FragmentSemanticRetriever(params.backend));
+        return (0, ts_utils_1.succeed)(new FragmentSemanticRetriever(params.backend, params.identityResolver));
     }
     /**
      * Embed `query.semantic`, query the fragment index, and return the per-fragment
@@ -58,6 +89,13 @@ class FragmentSemanticRetriever {
             return (0, ts_utils_1.fail)(exports.FRAGMENT_SEMANTIC_UNWIRED_MESSAGE);
         }
         const backend = this._backend;
+        // Resolve the narrowing FIRST. It is synchronous, local, and cheap, while
+        // `embedQuery` is typically a paid network round trip — so a typo'd `kind`, a
+        // missing resolver, or a half-supplied narrowing should cost nothing.
+        const options = this._resolveOptions(query);
+        if (options.isFailure()) {
+            return (0, ts_utils_1.fail)(options.message);
+        }
         // Consumer-supplied hooks may throw; normalize both a returned `fail` and a
         // rejection into a single `fragment recall: <label> failed` Failure so
         // `retrieve` always honors its `Promise<Result<...>>` contract.
@@ -65,7 +103,58 @@ class FragmentSemanticRetriever {
         if (embedded.isFailure()) {
             return (0, ts_utils_1.fail)(embedded.message);
         }
-        return FragmentSemanticRetriever._callBackend('fragment query', () => { var _a; return backend.fragmentIndex.query(embedded.value, (_a = query.topK) !== null && _a !== void 0 ? _a : 10, query.maxPerRecord); });
+        return FragmentSemanticRetriever._callBackend('fragment query', () => { var _a; return backend.fragmentIndex.query(embedded.value, (_a = query.topK) !== null && _a !== void 0 ? _a : 10, options.value); });
+    }
+    /**
+     * Turn the query's consumer-facing narrowing into the storage-address narrowing
+     * the index understands.
+     *
+     * @remarks
+     * `kind` selects the identity codec and the codec computes the record's storage
+     * address, so this is a deterministic resolution rather than a search —
+     * which is what makes a colliding `entityId` across kinds a non-issue.
+     *
+     * A **versioned** kind resolves to the entity's own subtree scope and deliberately
+     * carries no `id`, so the narrowing covers every version of the entity — including
+     * superseded ones, which are invalidated but never pruned from the index. A
+     * non-versioned kind resolves to exactly one record.
+     */
+    _resolveOptions(query) {
+        const { entityId, kind, maxPerRecord } = query;
+        if (entityId === undefined && kind === undefined) {
+            return (0, ts_utils_1.succeed)({ maxPerRecord });
+        }
+        if (entityId === undefined || kind === undefined) {
+            return (0, ts_utils_1.fail)(exports.FRAGMENT_NARROWING_INCOMPLETE_MESSAGE);
+        }
+        if (this._identityResolver === undefined) {
+            return (0, ts_utils_1.fail)(exports.FRAGMENT_NARROWING_UNRESOLVABLE_MESSAGE);
+        }
+        const resolver = this._identityResolver;
+        // `identityResolver` is a consumer-injectable seam like the two backend hooks,
+        // so a throw has to become a `Failure` here rather than escaping `retrieve()`
+        // and breaking its `Promise<Result<...>>` contract. `captureResult` yields a
+        // nested `Result`, which the identity `onSuccess` flattens.
+        return (0, ts_utils_1.captureResult)(() => resolver.resolveIdentity(kind, entityId))
+            .onSuccess((resolved) => resolved)
+            .withErrorFormat((msg) => `fragment recall: cannot resolve '${kind}'/'${entityId}': ${msg}`)
+            .onSuccess((address) => {
+            // A versioned kind's every version lives under the entity subtree the
+            // codec returned, so omitting `id` is what makes the narrowing mean
+            // "this entity" rather than "one of its versions".
+            if (address.isVersioned) {
+                return (0, ts_utils_1.succeed)({ maxPerRecord, scope: address.scope });
+            }
+            // `idStem` is a plain `string` on the codec result, but a `MemoryId` IS the
+            // filename stem by contract and `Convert.memoryId` is what enforces that —
+            // so validate rather than assert. A resolver that returned a path-unsafe
+            // stem could otherwise smuggle it into the index query, where it would
+            // match nothing and look like an empty result rather than a caller bug.
+            return types_1.Convert.memoryId
+                .convert(address.idStem)
+                .withErrorFormat((msg) => `fragment recall: '${kind}'/'${entityId}' resolved to an unusable record id: ${msg}`)
+                .onSuccess((id) => (0, ts_utils_1.succeed)({ maxPerRecord, scope: address.scope, id }));
+        });
     }
     /**
      * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`

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;;;;;;;;;;;;;;;;;;;;;;;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"]}
+{"version":3,"file":"fragmentSemanticRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/fragmentSemanticRetriever.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, captureResult, fail, succeed } from '@fgv/ts-utils';\nimport { Convert, EntityId, IIdentityCodecResult, IIdentityResolver, Kind, MemoryId } from '../types';\nimport { IFragmentQueryOptions, 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 loud-degradation message returned when a query carries a record narrowing but\n * no {@link IIdentityResolver} is wired to resolve it.\n *\n * @remarks\n * Deliberately a `Failure` rather than a silently-global search: answering a scoped\n * question with an unscoped result is the failure this narrowing exists to remove.\n * @public\n */\nexport const FRAGMENT_NARROWING_UNRESOLVABLE_MESSAGE: string =\n  'fragment recall: a record narrowing was supplied but no identity resolver is wired; pass one to FragmentSemanticRetriever.create';\n\n/**\n * The message returned when exactly one of `entityId` / `kind` is supplied.\n *\n * @remarks\n * They travel together because `kind` is what selects the identity codec, and the\n * codec is what makes the resolution unambiguous. One without the other is not a\n * partial narrowing that could be honored best-effort — it is not a narrowing at all.\n * @public\n */\nexport const FRAGMENT_NARROWING_INCOMPLETE_MESSAGE: string =\n  'fragment recall: `entityId` and `kind` must be supplied together — `kind` selects the identity codec that resolves the narrowing';\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   * Narrow the search to one record's fragments: the consumer-supplied domain key\n   * of the record to search within. **Must be supplied with\n   * {@link IFragmentQuery.kind}.**\n   *\n   * @remarks\n   * The narrowing is applied **during selection, before the `topK` cut**, so the\n   * `topK` you ask for is the `topK` you get. Filtering a global result afterwards\n   * is not equivalent: it truncates to `topK` across every record first, so a scoped\n   * search would come back short whenever other records outscored this one's\n   * fragments.\n   *\n   * For a versioned kind this narrows to **every version of the entity** — literally\n   * every version, superseded ones included, because invalidation stamps `invalid_at`\n   * without pruning that version's fragments. Nothing on a hit distinguishes a\n   * current fragment from a historical one. That matches the record-granular vector\n   * lane; it is not currency filtering.\n   */\n  readonly entityId?: EntityId;\n\n  /**\n   * The kind of the record named by {@link IFragmentQuery.entityId}. **Must be\n   * supplied with it.**\n   *\n   * @remarks\n   * This is not decoration and not a filter: `kind` **selects the identity codec**,\n   * and the codec computes the storage address. An `EntityId` promises no uniqueness\n   * beyond a scope — the same id under two kinds is the ordinary case, not a\n   * pathological one — so without `kind` the resolution is ambiguous, and with it\n   * ambiguity is structurally impossible.\n   */\n  readonly kind?: Kind;\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  private readonly _identityResolver: IIdentityResolver | undefined;\n\n  private constructor(\n    backend: IFragmentSemanticBackend | undefined,\n    identityResolver: IIdentityResolver | undefined\n  ) {\n    this._backend = backend;\n    this._identityResolver = identityResolver;\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  /**\n   * Family-convention factory.\n   *\n   * @param params - `backend` wires fragment recall itself. `identityResolver`\n   * resolves a query's `(kind, entityId)` narrowing to a storage address;\n   * `IMemoryStore` implements it, so the usual wiring is\n   * `{ backend, identityResolver: store }`. It is optional because an unscoped\n   * fragment search needs nothing to resolve — but a query that *does* carry a\n   * narrowing fails loudly without it rather than quietly searching everything.\n   */\n  public static create(params: {\n    readonly backend?: IFragmentSemanticBackend;\n    readonly identityResolver?: IIdentityResolver;\n  }): Result<FragmentSemanticRetriever> {\n    return succeed(new FragmentSemanticRetriever(params.backend, params.identityResolver));\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    // Resolve the narrowing FIRST. It is synchronous, local, and cheap, while\n    // `embedQuery` is typically a paid network round trip — so a typo'd `kind`, a\n    // missing resolver, or a half-supplied narrowing should cost nothing.\n    const options: Result<IFragmentQueryOptions> = this._resolveOptions(query);\n    if (options.isFailure()) {\n      return fail(options.message);\n    }\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, options.value)\n    );\n  }\n\n  /**\n   * Turn the query's consumer-facing narrowing into the storage-address narrowing\n   * the index understands.\n   *\n   * @remarks\n   * `kind` selects the identity codec and the codec computes the record's storage\n   * address, so this is a deterministic resolution rather than a search —\n   * which is what makes a colliding `entityId` across kinds a non-issue.\n   *\n   * A **versioned** kind resolves to the entity's own subtree scope and deliberately\n   * carries no `id`, so the narrowing covers every version of the entity — including\n   * superseded ones, which are invalidated but never pruned from the index. A\n   * non-versioned kind resolves to exactly one record.\n   */\n  private _resolveOptions(query: IFragmentQuery): Result<IFragmentQueryOptions> {\n    const { entityId, kind, maxPerRecord } = query;\n    if (entityId === undefined && kind === undefined) {\n      return succeed({ maxPerRecord });\n    }\n    if (entityId === undefined || kind === undefined) {\n      return fail(FRAGMENT_NARROWING_INCOMPLETE_MESSAGE);\n    }\n    if (this._identityResolver === undefined) {\n      return fail(FRAGMENT_NARROWING_UNRESOLVABLE_MESSAGE);\n    }\n    const resolver: IIdentityResolver = this._identityResolver;\n    // `identityResolver` is a consumer-injectable seam like the two backend hooks,\n    // so a throw has to become a `Failure` here rather than escaping `retrieve()`\n    // and breaking its `Promise<Result<...>>` contract. `captureResult` yields a\n    // nested `Result`, which the identity `onSuccess` flattens.\n    return captureResult(() => resolver.resolveIdentity(kind, entityId))\n      .onSuccess((resolved: Result<IIdentityCodecResult>) => resolved)\n      .withErrorFormat((msg) => `fragment recall: cannot resolve '${kind}'/'${entityId}': ${msg}`)\n      .onSuccess((address: IIdentityCodecResult) => {\n        // A versioned kind's every version lives under the entity subtree the\n        // codec returned, so omitting `id` is what makes the narrowing mean\n        // \"this entity\" rather than \"one of its versions\".\n        if (address.isVersioned) {\n          return succeed({ maxPerRecord, scope: address.scope });\n        }\n        // `idStem` is a plain `string` on the codec result, but a `MemoryId` IS the\n        // filename stem by contract and `Convert.memoryId` is what enforces that —\n        // so validate rather than assert. A resolver that returned a path-unsafe\n        // stem could otherwise smuggle it into the index query, where it would\n        // match nothing and look like an empty result rather than a caller bug.\n        return Convert.memoryId\n          .convert(address.idStem)\n          .withErrorFormat(\n            (msg) => `fragment recall: '${kind}'/'${entityId}' resolved to an unusable record id: ${msg}`\n          )\n          .onSuccess((id: MemoryId) => succeed({ maxPerRecord, scope: address.scope, id }));\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

@@ -1,6 +1,6 @@
 import { Logging, Result } from '@fgv/ts-utils';
 import { FileTree } from '@fgv/ts-json-base';
-import { DedupScope, EntityId, IIdentityCodec, IMemoryRecord, IWritePolicy, Kind, MemoryId, MemoryScopeKey, RankProjector } from '../types';
+import { DedupScope, EntityId, IIdentityCodecResult, IIdentityCodec, IMemoryRecord, IWritePolicy, Kind, MemoryId, MemoryScopeKey, RankProjector } from '../types';
 import { IBodyConverterRegistry as IRegistry } from '../converters';
 import { IDerivedStateCoverage } from './coverage';
 import { DerivedArtifact, ReconcileReport } from './reconcile';
@@ -325,6 +325,9 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
     listScoped(): Promise<Result<ReadonlyArray<IScopedMemoryRecord>>>;
     /** {@inheritDoc IMemoryRecordResolver.resolveRecord} */
     resolveRecord(scope: MemoryScopeKey, id: MemoryId): Result<IMemoryRecord<unknown> | undefined>;
+    private _codec;
+    /** {@inheritDoc IIdentityResolver.resolveIdentity} */
+    resolveIdentity(kind: Kind, entityId: EntityId): Result<IIdentityCodecResult>;
     /**
      * Materialize a selected set of entries into records, dropping any that have
      * vanished since selection.
@@ -597,7 +600,6 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      * than preserving it), so a ranking bug never loses an authoritative write.
      */
     private _stampRank;
-    private _codecFor;
     private _policyFor;
     /** {@inheritDoc IMemoryStore.dedupScopeFor} */
     dedupScopeFor(kind: Kind): DedupScope;