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

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

@@ -323,6 +323,13 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
     private readonly _logger;
     private readonly _vectorIndex;
     private readonly _embed;
+    private readonly _fragmentIndex;
+    private readonly _fragmentEmbedder;
+    /**
+     * Records the initial walk could not load. Populated during `create()` in
+     * {@link MemoryRecordErrorMode | `'skip'` mode}; empty otherwise.
+     */
+    private readonly _skippedRecords;
     /** Monotonic write counter; incremented inside the write-lock on each put. */
     private _seq;
     /**
@@ -343,6 +350,15 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      */
     private static readonly _mutableFieldAccessors;
     private constructor();
+    /**
+     * Records the initial vault walk could not parse or validate and quarantined
+     * (not indexed). Non-empty only when the store was opened with
+     * {@link MemoryRecordErrorMode | `onRecordError: 'skip'`} AND at least one
+     * record failed to load. Each entry identifies the offending file so a host
+     * can repair it; the file itself is never deleted or mutated, so a later open
+     * (after the body converter is fixed) re-indexes it.
+     */
+    get skippedRecords(): 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
@@ -430,6 +446,26 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      * failure).
      */
     private _embedOnWrite;
+    /**
+     * Best-effort fragment-embed-on-write. When a fragment index AND a fragment
+     * embedder are wired, chunks + embeds the built record and replaces its
+     * fragments in the index (`addFragments` is whole-record-replace, so a re-authored
+     * document never leaves stale fragments behind — no explicit remove needed). A
+     * failure (returned `fail` OR a thrown/rejected hook) is logged and the record is
+     * returned unchanged — the put still persists, and the fragment index is a derived
+     * view a later `rebuild` reconciles. Unlike {@link FileTreeMemoryStore._embedOnWrite}
+     * it stamps nothing on the record (fragments have no per-record `embeddingRef`
+     * analog). A pass-through no-op when unwired (byte-identical record).
+     */
+    private _embedFragmentsOnWrite;
+    /**
+     * Best-effort fragment removal. A no-op unless the full fragment lifecycle is
+     * wired (both an index AND an embedder), so an unwired store does no fragment
+     * work and behaves byte-identically. Failures are logged, never surfaced — a
+     * committed delete/eviction must not fail because a derived fragment index could
+     * not be pruned.
+     */
+    private _removeFragmentsBestEffort;
     /**
      * Evict the records named by a `cull-oldest` decision, best-effort. Runs only
      * after the authoritative `_persist`, so a failed eviction is logged (never
@@ -625,10 +661,83 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
     /**
      * Walk the FileTree once and rebuild the index. Also resumes the `seq`
      * counter past the highest persisted `seq` so new writes stay monotonic.
+     *
+     * In `'skip'` mode each per-record failure is captured structurally on
+     * `this._skippedRecords` (path + scope + path-tagged error) at its failure
+     * site and logged at `warn`; the walk keeps every record that loaded.
      */
     private _initialIndex;
     /** Recursively collect every `.md` record under `dir` (scope = path segments). */
     private _collectEntries;
+    /**
+     * Load and verify one record file. On failure in `'skip'` mode, records the
+     * structured {@link ISkippedRecord} identity (path + scope + path-tagged
+     * error) and logs the skip at `warn`; the failure is still returned so the
+     * caller's `mapSuccess` drops it from the loaded set. In `'fail'` mode the
+     * failure passes through untouched so the historical error is byte-identical.
+     */
+    private _loadRecordFile;
+}
+
+/**
+ * The loud-degradation message a {@link FragmentSemanticRetriever} returns when a
+ * fragment query is issued but no {@link IFragmentSemanticBackend | backend} is
+ * wired — the discovery surface NEVER answers a fragment query with a silent empty.
+ * @public
+ */
+export declare const FRAGMENT_SEMANTIC_UNWIRED_MESSAGE: string;
+
+/**
+ * The fragment-granular sibling of {@link MemoryEmbedder}: chunks a record's body
+ * and embeds each chunk, returning one {@link IEmbeddedFragment} per chunk. The
+ * chunking policy (window size, overlap) lives entirely in the consumer's embedder
+ * — the core stays chunking-agnostic, exactly as it stays embedder-agnostic for
+ * the record-granular path. Used by the store's fragment-embed-on-write hook.
+ * @public
+ */
+export declare type FragmentEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<ReadonlyArray<IEmbeddedFragment>>>;
+
+/**
+ * The sub-document semantic-search retriever — the "discovery" half of a
+ * search-then-read contract. It embeds a fragment query, queries the
+ * {@link IFragmentVectorIndex}, and returns the raw per-fragment
+ * {@link IVectorQueryHit | hits} (each carrying a record `target` AND the matched
+ * `locator`), NOT resolved records: the consumer re-reads each record and slices it
+ * by the locator on its own read side.
+ *
+ * @remarks
+ * Deliberately NOT an {@link IMemoryRetriever}: memory recall is record-granular and
+ * returns records; fragment discovery is span-granular and returns locators. Keeping
+ * it a distinct surface matches the consumer contract (memory stays record-granular;
+ * sub-document knowledge uses a separate fragment index) and avoids overloading the
+ * record retriever's return type with a locator that only makes sense here.
+ *
+ * When no backend is wired, `supportsFragmentRecall` is `false` and any fragment
+ * query degrades loudly ({@link FRAGMENT_SEMANTIC_UNWIRED_MESSAGE}) — it NEVER
+ * returns a silent empty. A consumer-supplied backend that rejects (throws) is
+ * normalized into a `Failure`.
+ * @public
+ */
+export declare class FragmentSemanticRetriever {
+    private readonly _backend;
+    private constructor();
+    /** What this retriever can do given its wiring. */
+    get capabilities(): IFragmentRetrieverCapabilities;
+    /** Family-convention factory. */
+    static create(params: {
+        readonly backend?: IFragmentSemanticBackend;
+    }): 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>>>;
+    /**
+     * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`
+     * and a thrown/rejected promise into a single `fragment recall: <label> failed`
+     * `Failure`.
+     */
+    private static _callBackend;
 }
 
 /**
@@ -906,6 +1015,19 @@ export declare interface IEdgeTarget {
     readonly id: MemoryId;
 }
 
+/**
+ * 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}.
+ * @public
+ */
+export declare interface IEmbeddedFragment {
+    /** The fragment's in-record span. */
+    readonly locator: IFragmentLocator;
+    /** The embedding vector for that span. */
+    readonly vector: Float32Array;
+}
+
 /**
  * A near-duplicate candidate surfaced to the {@link IEntityResolver} by stage-4
  * layer-2 similarity search: an existing record whose embedding is within the
@@ -1031,6 +1153,136 @@ export declare interface IFileTreeMemoryStoreCreateParams {
      * `rebuild` reconciles, so a vector failure never fails an authoritative write.
      */
     readonly embed?: MemoryEmbedder;
+    /**
+     * Optional fragment-granular vector index for sub-document semantic search.
+     * Wired together with
+     * {@link IFileTreeMemoryStoreCreateParams.fragmentEmbedder | fragmentEmbedder}:
+     * when both are present the store chunks + embeds each written record and
+     * maintains the fragment index on `put` / `delete` / cap-cull eviction — the
+     * "discovery" half of a search-then-read contract, queried through a
+     * {@link FragmentSemanticRetriever}. Independent of the record-granular
+     * {@link IFileTreeMemoryStoreCreateParams.vectorIndex | vectorIndex} pair: a
+     * store may wire record vectors, fragment vectors, both, or neither. Absent (or
+     * `fragmentEmbedder` absent) → no fragment work happens and the store behaves
+     * byte-identically (the additive, zero-overhead-when-unwired default).
+     */
+    readonly fragmentIndex?: IFragmentVectorIndex;
+    /**
+     * Optional fragment embedder applied to each record on write, wired together
+     * with {@link IFileTreeMemoryStoreCreateParams.fragmentIndex | fragmentIndex}.
+     * The consumer owns the chunking policy (window size, overlap) and the embedding
+     * call; the store stays chunking- and embedder-agnostic. Fragment index
+     * maintenance is **best-effort**, exactly like the record-vector path: a failed
+     * (or throwing) `fragmentEmbedder` / `addFragments` / `remove` is logged at
+     * `warn` and the record operation still succeeds — the fragment index is a
+     * derived view a later `rebuild` reconciles.
+     */
+    readonly fragmentEmbedder?: FragmentEmbedder;
+    /**
+     * How the initial vault walk reacts to a record that fails to parse or
+     * validate. Defaults to `'fail'` — one bad record fails the whole open, the
+     * historical behavior, preserved byte-for-byte. Set `'skip'` to quarantine
+     * unreadable records instead: valid records still load, each skip is logged
+     * at `warn` and surfaced on {@link FileTreeMemoryStore.skippedRecords}, and
+     * the offending file is left untouched for a later (post-fix) re-index. See
+     * {@link MemoryRecordErrorMode}.
+     */
+    readonly onRecordError?: MemoryRecordErrorMode;
+}
+
+/**
+ * A half-open `[start, end)` span into a record's body — the in-record locator a
+ * {@link IFragmentVectorIndex} carries on each fragment hit. `start` is inclusive,
+ * `end` exclusive. The unit (character / byte / token offsets) is the consumer's
+ * choice: the index stores the two integers opaquely and never interprets them,
+ * so they line up with whatever locator the consumer's own read side uses.
+ * @public
+ */
+export declare interface IFragmentLocator {
+    /** Inclusive start offset into the record body. */
+    readonly start: number;
+    /** Exclusive end offset into the record body. */
+    readonly end: number;
+}
+
+/**
+ * A sub-document semantic-search request: the natural-language `semantic` text to
+ * match, an optional `topK` result cap (default 10), and an optional
+ * `maxPerRecord` cap that keeps one long document from monopolizing the result.
+ * @public
+ */
+export declare interface IFragmentQuery {
+    /** The natural-language text to embed and match against stored fragments. */
+    readonly semantic: string;
+    /** Maximum number of fragment hits to return. Defaults to 10. */
+    readonly topK?: number;
+    /**
+     * Maximum number of fragments any single record may contribute to the result.
+     * Applied during selection (before the `topK` cut). Omit for uncapped.
+     */
+    readonly maxPerRecord?: number;
+}
+
+/**
+ * What a {@link FragmentSemanticRetriever} can do given its wiring.
+ * @public
+ */
+export declare interface IFragmentRetrieverCapabilities {
+    /** `true` when a fragment backend is wired and fragment recall is operational. */
+    readonly supportsFragmentRecall: boolean;
+}
+
+/**
+ * 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
+ * required together — a fragment index is useless without a way to embed the query.
+ * @public
+ */
+export declare interface IFragmentSemanticBackend {
+    /** The fragment-granular vector index to query. */
+    readonly fragmentIndex: IFragmentVectorIndex;
+    /** Turns the query text into a vector. */
+    readonly embedQuery: QueryEmbedder;
+}
+
+/**
+ * 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.
+ *
+ * @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
+ * record-granular; sub-document knowledge uses a separate fragment index.
+ * @public
+ */
+export declare interface IFragmentVectorIndex {
+    /**
+     * Add (or replace) all fragments for the scope-qualified `target`. Whole-record
+     * semantics: every fragment previously held for `target` is dropped and replaced
+     * by `fragments`, so a re-authored document never leaves stale fragments behind.
+     * Returns the number of fragments now held for the record.
+     */
+    addFragments(target: IEdgeTarget, fragments: ReadonlyArray<IEmbeddedFragment>): Promise<Result<number>>;
+    /**
+     * Remove every fragment for the scope-qualified `target`. Returns the removed
+     * target. Idempotent — removing a target with no fragments still succeeds.
+     */
+    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
+     * `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.
+     */
+    query(vector: Float32Array, topK: number, maxPerRecord?: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
 }
 
 /**
@@ -1867,6 +2119,77 @@ export declare class InMemoryCosineIndex implements IVectorIndex {
     private static _cosine;
 }
 
+/**
+ * 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.
+ *
+ * @remarks
+ * Same regime and same non-goals as {@link InMemoryCosineIndex}: no external
+ * dependency, no ANN structure, a linear scan over the stored fragments — the seam
+ * ({@link IFragmentVectorIndex}) stays open for a consumer to swap a persistent /
+ * ANN backend once N grows. `addFragments` is whole-record-replace, so re-authoring
+ * a document never leaves stale fragments behind. The index has a single dimension
+ * established by the first fragment added; every subsequent fragment and every
+ * `query` vector must match it or fail loudly — a mismatched dimension is an
+ * embedder-wiring bug, never a silent zero-similarity result.
+ * {@link InMemoryFragmentCosineIndex.rebuild | rebuild} clears the index (and the
+ * established dimension), so a re-embed with a different model is supported.
+ *
+ * The optional `maxPerRecord` cap on `query` is applied **during selection**, before
+ * the `topK` cut, so one long document with many strong fragments cannot crowd every
+ * other record out of the result.
+ * @public
+ */
+export declare class InMemoryFragmentCosineIndex implements IFragmentVectorIndex {
+    /**
+     * Stored fragments keyed by the canonical {@link edgeTargetKey} of the record's
+     * scope-qualified address, so two records that share a filename stem across
+     * scopes occupy distinct entries and never overwrite each other's fragments.
+     */
+    private readonly _records;
+    /** The dimension of every stored fragment vector; `undefined` until the first `add`. */
+    private _dimension;
+    private constructor();
+    /** The number of records that currently have at least one stored fragment. */
+    get recordCount(): number;
+    /** The total number of fragments currently held across all records. */
+    get fragmentCount(): number;
+    /** Family-convention factory. */
+    static create(): Result<InMemoryFragmentCosineIndex>;
+    /** {@inheritDoc IFragmentVectorIndex.addFragments} */
+    addFragments(target: IEdgeTarget, fragments: ReadonlyArray<IEmbeddedFragment>): Promise<Result<number>>;
+    /** {@inheritDoc IFragmentVectorIndex.remove} */
+    remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
+    /** {@inheritDoc IFragmentVectorIndex.query} */
+    query(vector: Float32Array, topK: number, maxPerRecord?: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    /**
+     * Re-embed every record from `source` and rebuild the fragment index from
+     * scratch. Clears the current contents (and the established dimension) first, so
+     * a re-embed with a different model is supported. Returns the total number of
+     * fragments indexed.
+     *
+     * On any failure (list, embed, or add) the index is rolled back to empty rather
+     * than left in a partially-rebuilt state.
+     *
+     * @param source - The scope-qualified record source to re-embed.
+     * @param embed - The fragment embedder applied to each record.
+     */
+    rebuild(source: IMemoryRecordSource, embed: FragmentEmbedder): Promise<Result<number>>;
+    /** Empty the index and forget the established dimension. */
+    private _reset;
+    /** The Euclidean magnitude (L2 norm) of a vector. */
+    private static _magnitude;
+    /**
+     * Cosine similarity between the query (whose magnitude is precomputed once and
+     * reused across the scan) and a stored fragment vector. A zero-magnitude vector
+     * on either side yields `0` rather than `NaN`.
+     */
+    private static _cosine;
+}
+
 /**
  * Structured provenance for a record or an edge. Never a flat enum — the
  * `[key: string]: unknown` index signature lets a consumer attach an opaque
@@ -1981,6 +2304,21 @@ export declare interface ISemanticRetrieverCreateParams {
     readonly backend?: ISemanticBackend;
 }
 
+/**
+ * A record that {@link FileTreeMemoryStore.create} could not load and
+ * quarantined (only produced in {@link MemoryRecordErrorMode | `'skip'` mode}).
+ * The `path` identifies WHICH record was skipped so a host can repair it.
+ * @public
+ */
+export declare interface ISkippedRecord {
+    /** The record file's path within the vault (`<scope>/<filename>.md`). */
+    readonly path: string;
+    /** The scope the record lives under (its parent directory path). */
+    readonly scope: MemoryScopeKey;
+    /** The parse/validation failure message (includes the record path). */
+    readonly error: string;
+}
+
 /**
  * Narrow an {@link IIdentityCodec} to {@link ITemporalIdentityCodec} by probing
  * for the versioned methods. Used by the store when an `encode` result reports
@@ -2101,10 +2439,11 @@ export declare interface IVectorIndex {
 }
 
 /**
- * A single hit returned by {@link IVectorIndex.query}: the matched record's
- * scope-qualified {@link IEdgeTarget | address} and the backend's similarity
- * score (higher = more similar; the exact scale is backend-defined). Hits are
- * returned in descending score order.
+ * A single hit returned by {@link IVectorIndex.query} (or
+ * {@link IFragmentVectorIndex.query}): the matched record's scope-qualified
+ * {@link IEdgeTarget | address} and the backend's similarity score (higher = more
+ * similar; the exact scale is backend-defined). Hits are returned in descending
+ * score order.
  *
  * @remarks
  * The address is a `(scope, id)` pair, NOT a bare {@link MemoryId} — per-scope
@@ -2112,6 +2451,10 @@ export declare interface IVectorIndex {
  * stem under different scopes, so a bare id could not disambiguate two records
  * that share a stem. The caller re-resolves the hit against the record index by
  * the same scoped address.
+ *
+ * `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.
  * @public
  */
 export declare interface IVectorQueryHit {
@@ -2119,6 +2462,8 @@ 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. */
+    readonly locator?: IFragmentLocator;
 }
 
 /**
@@ -2761,6 +3106,24 @@ export declare class MemoryObservationStore implements IMemoryObserver {
     private static _matches;
 }
 
+/**
+ * Policy for how {@link FileTreeMemoryStore.create}'s initial vault walk reacts
+ * to a record that fails to parse or validate.
+ *
+ * - `'fail'` (the default) — one unreadable record fails the whole open. The
+ *   walk collapses per-record results with `mapResults`, so any single failure
+ *   aborts `create()`. This is the historical behavior, preserved byte-for-byte.
+ * - `'skip'` — an unreadable record is quarantined (not indexed) rather than
+ *   failing the open. Every record that DOES parse loads normally; each skip is
+ *   logged at `warn` and surfaced structurally on
+ *   {@link FileTreeMemoryStore.skippedRecords}. The offending file is never
+ *   deleted or mutated, so a later open (after the body converter is fixed)
+ *   re-indexes it. A vault holds every kind in one store, so a required-field
+ *   migration on one kind must not make every other record unreadable.
+ * @public
+ */
+export declare type MemoryRecordErrorMode = 'skip' | 'fail';
+
 /**
  * Scope path segment. May be multi-segment (`/`-separated) for kinds whose
  * codec maps an entity into a sub-tree (e.g. MTM: `conversations/<id>`). The

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

@@ -121,6 +121,22 @@ export class FileTreeMemoryStore implements IMemoryStore {
     list(filter?: IMemoryStoreListFilter): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
     listScoped(): Promise<Result<ReadonlyArray<IScopedMemoryRecord>>>;
     put(record: IMemoryRecord<unknown>): Promise<Result<IMemoryRecord<unknown>>>;
+    get skippedRecords(): ReadonlyArray<ISkippedRecord>;
+}
+
+// @public
+export const FRAGMENT_SEMANTIC_UNWIRED_MESSAGE: string;
+
+// @public
+export type FragmentEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<ReadonlyArray<IEmbeddedFragment>>>;
+
+// @public
+export class FragmentSemanticRetriever {
+    get capabilities(): IFragmentRetrieverCapabilities;
+    static create(params: {
+        readonly backend?: IFragmentSemanticBackend;
+    }): Result<FragmentSemanticRetriever>;
+    retrieve(query: IFragmentQuery): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
 }
 
 // @public
@@ -203,6 +219,12 @@ export interface IEdgeTarget {
     readonly scope: MemoryScopeKey;
 }
 
+// @public
+export interface IEmbeddedFragment {
+    readonly locator: IFragmentLocator;
+    readonly vector: Float32Array;
+}
+
 // @public
 export interface IEntityResolutionCandidate {
     readonly record: IMemoryRecord<unknown>;
@@ -226,8 +248,11 @@ export interface IFileTreeMemoryStoreCreateParams {
     readonly codecs?: ReadonlyMap<Kind, IIdentityCodec>;
     readonly defaultCodec?: IIdentityCodec;
     readonly embed?: MemoryEmbedder;
+    readonly fragmentEmbedder?: FragmentEmbedder;
+    readonly fragmentIndex?: IFragmentVectorIndex;
     readonly logger?: Logging.ILogger;
     readonly observers?: ReadonlyArray<IMemoryObserver>;
+    readonly onRecordError?: MemoryRecordErrorMode;
     readonly rankProjectors?: ReadonlyMap<Kind, RankProjector>;
     readonly registry: IBodyConverterRegistry;
     readonly root: FileTree.IMutableFileTreeDirectoryItem;
@@ -236,6 +261,37 @@ export interface IFileTreeMemoryStoreCreateParams {
     readonly writePolicies?: ReadonlyMap<Kind, IWritePolicy>;
 }
 
+// @public
+export interface IFragmentLocator {
+    readonly end: number;
+    readonly start: number;
+}
+
+// @public
+export interface IFragmentQuery {
+    readonly maxPerRecord?: number;
+    readonly semantic: string;
+    readonly topK?: number;
+}
+
+// @public
+export interface IFragmentRetrieverCapabilities {
+    readonly supportsFragmentRecall: boolean;
+}
+
+// @public
+export interface IFragmentSemanticBackend {
+    readonly embedQuery: QueryEmbedder;
+    readonly fragmentIndex: IFragmentVectorIndex;
+}
+
+// @public
+export interface IFragmentVectorIndex {
+    addFragments(target: IEdgeTarget, fragments: ReadonlyArray<IEmbeddedFragment>): Promise<Result<number>>;
+    query(vector: Float32Array, topK: number, maxPerRecord?: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
+}
+
 // @public
 export interface IIdentityCodec {
     decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId>;
@@ -495,6 +551,17 @@ export class InMemoryCosineIndex implements IVectorIndex {
     get size(): number;
 }
 
+// @public
+export class InMemoryFragmentCosineIndex implements IFragmentVectorIndex {
+    addFragments(target: IEdgeTarget, fragments: ReadonlyArray<IEmbeddedFragment>): Promise<Result<number>>;
+    static create(): Result<InMemoryFragmentCosineIndex>;
+    get fragmentCount(): number;
+    query(vector: Float32Array, topK: number, maxPerRecord?: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    rebuild(source: IMemoryRecordSource, embed: FragmentEmbedder): Promise<Result<number>>;
+    get recordCount(): number;
+    remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
+}
+
 // @public
 export interface IProvenance {
     readonly [key: string]: unknown;
@@ -540,6 +607,13 @@ export interface ISemanticRetrieverCreateParams {
     readonly index: IMemoryIndex;
 }
 
+// @public
+export interface ISkippedRecord {
+    readonly error: string;
+    readonly path: string;
+    readonly scope: MemoryScopeKey;
+}
+
 // @public
 export function isTemporalIdentityCodec(codec: IIdentityCodec): codec is ITemporalIdentityCodec;
 
@@ -579,6 +653,7 @@ export interface IVectorIndex {
 
 // @public
 export interface IVectorQueryHit {
+    readonly locator?: IFragmentLocator;
     readonly score: number;
     readonly target: IEdgeTarget;
 }
@@ -698,6 +773,9 @@ export class MemoryObservationStore implements IMemoryObserver {
     get size(): number;
 }
 
+// @public
+export type MemoryRecordErrorMode = 'skip' | 'fail';
+
 // @public
 export type MemoryScopeKey = Brand<string, 'MemoryScopeKey'>;
 

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

@@ -0,0 +1,90 @@
+import { Result } from '@fgv/ts-utils';
+import { IFragmentVectorIndex, IVectorQueryHit } from '../vector';
+import { QueryEmbedder } from './semanticRetriever';
+/**
+ * The loud-degradation message a {@link FragmentSemanticRetriever} returns when a
+ * fragment query is issued but no {@link IFragmentSemanticBackend | backend} is
+ * wired — the discovery surface NEVER answers a fragment query with a silent empty.
+ * @public
+ */
+export declare const FRAGMENT_SEMANTIC_UNWIRED_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
+ * required together — a fragment index is useless without a way to embed the query.
+ * @public
+ */
+export interface IFragmentSemanticBackend {
+    /** The fragment-granular vector index to query. */
+    readonly fragmentIndex: IFragmentVectorIndex;
+    /** Turns the query text into a vector. */
+    readonly embedQuery: QueryEmbedder;
+}
+/**
+ * A sub-document semantic-search request: the natural-language `semantic` text to
+ * match, an optional `topK` result cap (default 10), and an optional
+ * `maxPerRecord` cap that keeps one long document from monopolizing the result.
+ * @public
+ */
+export interface IFragmentQuery {
+    /** The natural-language text to embed and match against stored fragments. */
+    readonly semantic: string;
+    /** Maximum number of fragment hits to return. Defaults to 10. */
+    readonly topK?: number;
+    /**
+     * Maximum number of fragments any single record may contribute to the result.
+     * Applied during selection (before the `topK` cut). Omit for uncapped.
+     */
+    readonly maxPerRecord?: number;
+}
+/**
+ * What a {@link FragmentSemanticRetriever} can do given its wiring.
+ * @public
+ */
+export interface IFragmentRetrieverCapabilities {
+    /** `true` when a fragment backend is wired and fragment recall is operational. */
+    readonly supportsFragmentRecall: boolean;
+}
+/**
+ * The sub-document semantic-search retriever — the "discovery" half of a
+ * search-then-read contract. It embeds a fragment query, queries the
+ * {@link IFragmentVectorIndex}, and returns the raw per-fragment
+ * {@link IVectorQueryHit | hits} (each carrying a record `target` AND the matched
+ * `locator`), NOT resolved records: the consumer re-reads each record and slices it
+ * by the locator on its own read side.
+ *
+ * @remarks
+ * Deliberately NOT an {@link IMemoryRetriever}: memory recall is record-granular and
+ * returns records; fragment discovery is span-granular and returns locators. Keeping
+ * it a distinct surface matches the consumer contract (memory stays record-granular;
+ * sub-document knowledge uses a separate fragment index) and avoids overloading the
+ * record retriever's return type with a locator that only makes sense here.
+ *
+ * When no backend is wired, `supportsFragmentRecall` is `false` and any fragment
+ * query degrades loudly ({@link FRAGMENT_SEMANTIC_UNWIRED_MESSAGE}) — it NEVER
+ * returns a silent empty. A consumer-supplied backend that rejects (throws) is
+ * normalized into a `Failure`.
+ * @public
+ */
+export declare class FragmentSemanticRetriever {
+    private readonly _backend;
+    private constructor();
+    /** What this retriever can do given its wiring. */
+    get capabilities(): IFragmentRetrieverCapabilities;
+    /** Family-convention factory. */
+    static create(params: {
+        readonly backend?: IFragmentSemanticBackend;
+    }): 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>>>;
+    /**
+     * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`
+     * and a thrown/rejected promise into a single `fragment recall: <label> failed`
+     * `Failure`.
+     */
+    private static _callBackend;
+}
+//# sourceMappingURL=fragmentSemanticRetriever.d.ts.map

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

@@ -0,0 +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"}