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

package/lib/packlets/retrieve/fragmentSemanticRetriever.js

@@ -0,0 +1,82 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FragmentSemanticRetriever = exports.FRAGMENT_SEMANTIC_UNWIRED_MESSAGE = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * 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
+ */
+exports.FRAGMENT_SEMANTIC_UNWIRED_MESSAGE = 'fragment recall: no fragment index is wired; wire an IFragmentSemanticBackend to enable sub-document search';
+/**
+ * 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
+ */
+class FragmentSemanticRetriever {
+    constructor(backend) {
+        this._backend = backend;
+    }
+    /** What this retriever can do given its wiring. */
+    get capabilities() {
+        return { supportsFragmentRecall: this._backend !== undefined };
+    }
+    /** Family-convention factory. */
+    static create(params) {
+        return (0, ts_utils_1.succeed)(new FragmentSemanticRetriever(params.backend));
+    }
+    /**
+     * Embed `query.semantic`, query the fragment index, and return the per-fragment
+     * hits in descending score order. Fails loudly when no backend is wired.
+     */
+    async retrieve(query) {
+        if (this._backend === undefined) {
+            return (0, ts_utils_1.fail)(exports.FRAGMENT_SEMANTIC_UNWIRED_MESSAGE);
+        }
+        const backend = this._backend;
+        // 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.
+        const embedded = await FragmentSemanticRetriever._callBackend('query embedding', () => backend.embedQuery(query.semantic));
+        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); });
+    }
+    /**
+     * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`
+     * and a thrown/rejected promise into a single `fragment recall: <label> failed`
+     * `Failure`.
+     */
+    static async _callBackend(label, op) {
+        try {
+            return (await op()).withErrorFormat((msg) => `fragment recall: ${label} failed: ${msg}`);
+        }
+        catch (err) {
+            return (0, ts_utils_1.fail)(`fragment recall: ${label} failed: ${String(err)}`);
+        }
+    }
+}
+exports.FragmentSemanticRetriever = FragmentSemanticRetriever;
+//# sourceMappingURL=fragmentSemanticRetriever.js.map

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

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

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

@@ -4,6 +4,7 @@ export * from './linkTraversalRetriever';
 export * from './tagRetriever';
 export * from './structuredFilterRetriever';
 export * from './semanticRetriever';
+export * from './fragmentSemanticRetriever';
 export * from './temporalRetrievers';
 export * from './hybridRetriever';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/retrieve/index.ts"],"names":[],"mappings":"AAKA,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/retrieve/index.ts"],"names":[],"mappings":"AAKA,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC"}

package/lib/packlets/retrieve/index.js

@@ -24,6 +24,7 @@ __exportStar(require("./linkTraversalRetriever"), exports);
 __exportStar(require("./tagRetriever"), exports);
 __exportStar(require("./structuredFilterRetriever"), exports);
 __exportStar(require("./semanticRetriever"), exports);
+__exportStar(require("./fragmentSemanticRetriever"), exports);
 __exportStar(require("./temporalRetrievers"), exports);
 __exportStar(require("./hybridRetriever"), exports);
 //# sourceMappingURL=index.js.map

package/lib/packlets/retrieve/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAEH,8CAA4B;AAC5B,qDAAmC;AACnC,2DAAyC;AACzC,iDAA+B;AAC/B,8DAA4C;AAC5C,sDAAoC;AACpC,uDAAqC;AACrC,oDAAkC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './retriever';\nexport * from './recencyRetriever';\nexport * from './linkTraversalRetriever';\nexport * from './tagRetriever';\nexport * from './structuredFilterRetriever';\nexport * from './semanticRetriever';\nexport * from './temporalRetrievers';\nexport * from './hybridRetriever';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAEH,8CAA4B;AAC5B,qDAAmC;AACnC,2DAAyC;AACzC,iDAA+B;AAC/B,8DAA4C;AAC5C,sDAAoC;AACpC,8DAA4C;AAC5C,uDAAqC;AACrC,oDAAkC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './retriever';\nexport * from './recencyRetriever';\nexport * from './linkTraversalRetriever';\nexport * from './tagRetriever';\nexport * from './structuredFilterRetriever';\nexport * from './semanticRetriever';\nexport * from './fragmentSemanticRetriever';\nexport * from './temporalRetrievers';\nexport * from './hybridRetriever';\n"]}

package/lib/packlets/store/fileTreeMemoryStore.d.ts

@@ -3,7 +3,7 @@ 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 { IMemoryObserver } from '../observe';
-import { IMemoryRecordSource, IScopedMemoryRecord, IVectorIndex, MemoryEmbedder } from '../vector';
+import { FragmentEmbedder, IFragmentVectorIndex, IMemoryRecordSource, IScopedMemoryRecord, IVectorIndex, MemoryEmbedder } from '../vector';
 /**
  * Filter for {@link IMemoryStore.list}. All present fields are ANDed together.
  * @public
@@ -22,6 +22,37 @@ export interface IMemoryStoreListFilter {
      */
     readonly asOf?: number;
 }
+/**
+ * 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 type MemoryRecordErrorMode = 'skip' | 'fail';
+/**
+ * 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 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;
+}
 /**
  * The writable, FileTree-backed, content-hash-deduped memory store.
  * @public
@@ -149,6 +180,41 @@ export 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;
 }
 /**
  * Flat-layout, FileTree-backed {@link IMemoryStore}. The FileTree is the source
@@ -180,6 +246,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;
     /**
@@ -200,6 +273,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
@@ -287,6 +369,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
@@ -482,9 +584,21 @@ 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;
 }
 //# sourceMappingURL=fileTreeMemoryStore.d.ts.map

package/lib/packlets/store/fileTreeMemoryStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fileTreeMemoryStore.d.ts","sourceRoot":"","sources":["../../../src/packlets/store/fileTreeMemoryStore.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fileTreeMemoryStore.d.ts","sourceRoot":"","sources":["../../../src/packlets/store/fileTreeMemoryStore.ts"],"names":[],"mappings":"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"}

package/lib/packlets/store/fileTreeMemoryStore.js

@@ -44,10 +44,24 @@ class FileTreeMemoryStore {
         this._logger = params.logger;
         this._vectorIndex = params.vectorIndex;
         this._embed = params.embed;
+        this._fragmentIndex = params.fragmentIndex;
+        this._fragmentEmbedder = params.fragmentEmbedder;
+        this._skippedRecords = [];
         this._seq = 0;
         this._observationSeq = 0;
         this._writeTail = Promise.resolve();
     }
+    /**
+     * 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() {
+        return this._skippedRecords;
+    }
     /**
      * Family-convention factory. Builds the derived index and a default LWW
      * policy, then performs an initial FileTree walk so an existing vault is
@@ -55,7 +69,7 @@ class FileTreeMemoryStore {
      */
     static create(params) {
         return types_1.KnowledgeLwwPolicy.create().onSuccess((defaultPolicy) => index_1.MemoryIndex.create().onSuccess((index) => {
-            var _a, _b, _c, _d, _e, _f, _g;
+            var _a, _b, _c, _d, _e, _f, _g, _h;
             const store = new FileTreeMemoryStore({
                 root: params.root,
                 registry: params.registry,
@@ -70,9 +84,11 @@ class FileTreeMemoryStore {
                 observers: (_f = params.observers) !== null && _f !== void 0 ? _f : [],
                 logger: (_g = params.logger) !== null && _g !== void 0 ? _g : new ts_utils_1.Logging.NoOpLogger(),
                 vectorIndex: params.vectorIndex,
-                embed: params.embed
+                embed: params.embed,
+                fragmentIndex: params.fragmentIndex,
+                fragmentEmbedder: params.fragmentEmbedder
             });
-            return store._initialIndex().onSuccess(() => (0, ts_utils_1.succeed)(store));
+            return store._initialIndex((_h = params.onRecordError) !== null && _h !== void 0 ? _h : 'fail').onSuccess(() => (0, ts_utils_1.succeed)(store));
         }));
     }
     /** {@inheritDoc IMemoryStore.get} */
@@ -389,6 +405,7 @@ class FileTreeMemoryStore {
         return this._buildRecord(record, body, existing, policy, hash)
             .onSuccess((built) => (0, ts_utils_1.succeed)(this._stampRank(built)))
             .thenOnSuccess((built) => this._embedOnWrite(built, scope))
+            .thenOnSuccess((built) => this._embedFragmentsOnWrite(built, scope))
             .onSuccess((embeddedBuilt) => this._persist(embeddedBuilt, scope, idStem))
             .thenOnSuccess(async (persisted) => {
             // Everything after the authoritative `_persist` commit is best-effort and
@@ -431,6 +448,45 @@ class FileTreeMemoryStore {
         }
         return (0, ts_utils_1.succeed)({ envelope: Object.assign(Object.assign({}, built.envelope), { embeddingRef: added.value }), body: built.body });
     }
+    /**
+     * 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).
+     */
+    async _embedFragmentsOnWrite(built, scope) {
+        if (this._fragmentIndex === undefined || this._fragmentEmbedder === undefined) {
+            return (0, ts_utils_1.succeed)(built);
+        }
+        const fragmentIndex = this._fragmentIndex;
+        const fragmentEmbedder = this._fragmentEmbedder;
+        const target = { scope, id: built.envelope.id };
+        const embedded = await this._tryVectorOp(() => fragmentEmbedder(built), `fragment embedding '${built.envelope.id}'`);
+        if (embedded.isFailure()) {
+            return (0, ts_utils_1.succeed)(built);
+        }
+        await this._tryVectorOp(() => fragmentIndex.addFragments(target, embedded.value), `fragment add for '${built.envelope.id}'`);
+        return (0, ts_utils_1.succeed)(built);
+    }
+    /**
+     * 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.
+     */
+    async _removeFragmentsBestEffort(target) {
+        if (this._fragmentIndex === undefined || this._fragmentEmbedder === undefined) {
+            return;
+        }
+        const fragmentIndex = this._fragmentIndex;
+        await this._tryVectorOp(() => fragmentIndex.remove(target), `fragment removal for '${target.id}'`);
+    }
     /**
      * Evict the records named by a `cull-oldest` decision, best-effort. Runs only
      * after the authoritative `_persist`, so a failed eviction is logged (never
@@ -463,6 +519,7 @@ class FileTreeMemoryStore {
     async _removeEvictedVectors(evicted, scope) {
         for (const id of evicted) {
             await this._removeVectorBestEffort({ scope, id });
+            await this._removeFragmentsBestEffort({ scope, id });
         }
     }
     /**
@@ -479,7 +536,7 @@ class FileTreeMemoryStore {
             result = (0, ts_utils_1.fail)(`${label} threw: ${String(err)}`);
         }
         if (result.isFailure()) {
-            this._warnSwallowed(`memory: ${label} failed (best-effort; vector index left for rebuild): ${result.message}`);
+            this._warnSwallowed(`memory: ${label} failed (best-effort; derived index left for rebuild): ${result.message}`);
         }
         return result;
     }
@@ -566,6 +623,7 @@ class FileTreeMemoryStore {
                 .onSuccess(() => this._index.patch('delete', { scope, record: existing }))
                 .thenOnSuccess(async () => {
                 await this._removeVectorBestEffort({ scope, id: existing.envelope.id });
+                await this._removeFragmentsBestEffort({ scope, id: existing.envelope.id });
                 return (0, ts_utils_1.succeed)(existing.envelope.id);
             });
         });
@@ -652,6 +710,7 @@ class FileTreeMemoryStore {
                     .thenOnSuccess((versionStem) => this._buildVersionedRecord(record, body, current, policy, hash, versionStem, validAt, now, seq)
                     .onSuccess((built) => (0, ts_utils_1.succeed)(this._stampRank(built)))
                     .thenOnSuccess((built) => this._embedOnWrite(built, scope))
+                    .thenOnSuccess((built) => this._embedFragmentsOnWrite(built, scope))
                     .onSuccess((embeddedBuilt) => this._persist(embeddedBuilt, scope, versionStem))
                     .onSuccess((persisted) => this._invalidateCurrents(scope, priorCurrents, validAt, now).onSuccess(() => (0, ts_utils_1.succeed)(persisted)))
                     .onSuccess((persisted) => (0, ts_utils_1.succeed)({ record: persisted, evicted: [] })));
@@ -988,9 +1047,13 @@ class FileTreeMemoryStore {
     /**
      * 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.
      */
-    _initialIndex() {
-        return this._collectEntries(this._root, []).onSuccess((entries) => this._index.rebuild(entries).onSuccess(() => {
+    _initialIndex(onRecordError) {
+        return this._collectEntries(this._root, [], onRecordError).onSuccess((entries) => this._index.rebuild(entries).onSuccess(() => {
             for (const entry of entries) {
                 if (entry.record.envelope.seq > this._seq) {
                     this._seq = entry.record.envelope.seq;
@@ -1000,11 +1063,11 @@ class FileTreeMemoryStore {
         }));
     }
     /** Recursively collect every `.md` record under `dir` (scope = path segments). */
-    _collectEntries(dir, scopeSegments) {
+    _collectEntries(dir, scopeSegments, onRecordError) {
         return dir.getChildren().onSuccess((children) => {
             const results = children.map((child) => {
                 if (child.type === 'directory') {
-                    return this._collectEntries(child, [...scopeSegments, child.name]);
+                    return this._collectEntries(child, [...scopeSegments, child.name], onRecordError);
                 }
                 if (!child.name.endsWith(MEMORY_FILE_EXTENSION) || scopeSegments.length === 0) {
                     // Skip non-record files and any record-shaped file sitting at the root
@@ -1012,15 +1075,43 @@ class FileTreeMemoryStore {
                     return (0, ts_utils_1.succeed)([]);
                 }
                 const scope = scopeSegments.join('/');
-                return child
-                    .getRawContents()
-                    .onSuccess((raw) => (0, converters_1.parseMemoryFile)(raw, this._registry))
-                    .onSuccess((parsedRecord) => this._verifyLoaded(scope, child, parsedRecord))
-                    .onSuccess((verified) => (0, ts_utils_1.succeed)([{ scope, record: verified }]));
+                return this._loadRecordFile(scope, child, onRecordError);
             });
+            // `'skip'` mode: keep every record that parsed, drop the ones that failed
+            // in a single pass (each failure is captured on `this._skippedRecords` and
+            // warn-logged at its site in `_loadRecordFile`). `.orDefault([])` covers
+            // the all-invalid-subtree edge where `mapSuccess` returns Failure because
+            // no element succeeded. `'fail'` mode: `mapResults` fails the whole open on
+            // any bad record — byte-identical to the historical load path.
+            if (onRecordError === 'skip') {
+                return (0, ts_utils_1.succeed)((0, ts_utils_1.mapSuccess)(results).orDefault([]).flat());
+            }
             return (0, ts_utils_1.mapResults)(results).onSuccess((perChild) => (0, ts_utils_1.succeed)(perChild.flat()));
         });
     }
+    /**
+     * 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.
+     */
+    _loadRecordFile(scope, child, onRecordError) {
+        return child
+            .getRawContents()
+            .onSuccess((raw) => (0, converters_1.parseMemoryFile)(raw, this._registry))
+            .onSuccess((parsedRecord) => this._verifyLoaded(scope, child, parsedRecord))
+            .onSuccess((verified) => (0, ts_utils_1.succeed)([{ scope, record: verified }]))
+            .onFailure((message) => {
+            if (onRecordError === 'skip') {
+                const path = `${scope}/${child.name}`;
+                const error = `memory record '${path}': ${message}`;
+                this._skippedRecords.push({ path, scope, error });
+                this._warnSwallowed(error);
+            }
+            return (0, ts_utils_1.fail)(message);
+        });
+    }
 }
 exports.FileTreeMemoryStore = FileTreeMemoryStore;
 /**