@fgv/ts-agent-memory 5.1.0-47 → 5.1.0-49

package/dist/packlets/store/vectorMaintenance.js

@@ -0,0 +1,251 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { fail, succeed } from '@fgv/ts-utils';
+/**
+ * Project a record the embedder **declined** into its written form: the same
+ * record with no `embeddingRef`, plus the vector (if any) that reference
+ * superseded, for the caller to prune after the commit.
+ *
+ * @remarks
+ * A decline says "this record is intentionally not embedded". A re-put of a
+ * record that *was* embedded (or a caller who supplied an `embeddingRef` — the
+ * field is store-derived by contract but nothing strips it) arrives here
+ * carrying an inherited reference, so returning it unchanged would persist
+ * `embeddingRef` on a record the store just decided not to embed.
+ *
+ * Clearing the reference alone would be cosmetic and arguably worse: the index
+ * entry keyed on this target would survive, so a semantic query would keep
+ * returning the record — scored on its **previous** content — while the record
+ * itself claimed not to be indexed. So the vector goes too, via
+ * `pruneStaleVector` once the write has committed.
+ * `stale` is set only when a reference was actually inherited, which keeps the
+ * common decline (a record that was never embedded) free of an index round
+ * trip.
+ *
+ * Pure and static: the decision needs nothing from the instance, and deferring
+ * the index call to the caller is what lets it run on the far side of
+ * `_persist`.
+ */
+function declineEmbedding(built, index, target, embed) {
+    if (built.envelope.embeddingRef === undefined) {
+        return { record: built, embed };
+    }
+    // Rest-spread rather than `embeddingRef: undefined`: the envelope is YAML-
+    // serialized, and an explicitly-undefined key is a serializer-dependent way
+    // to say "absent" where dropping the key is not.
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const _a = built.envelope, { embeddingRef } = _a, envelope = __rest(_a, ["embeddingRef"]);
+    return { record: { envelope, body: built.body }, stale: { index, target }, embed };
+}
+/**
+ * The store's record- and fragment-vector maintenance, extracted from
+ * {@link FileTreeMemoryStore} as a collaborator.
+ *
+ * @remarks
+ * Everything here is **best-effort by contract**: the durable record store is
+ * authoritative and both indexes are derived, rebuildable views, so a failed
+ * embed, add or remove is logged and the write still succeeds. Nothing in this
+ * class can turn a committed write into a `Failure` — which is exactly why it
+ * separates cleanly from the store's write path, where every step is fallible
+ * and fatal.
+ *
+ * The split is behavior-preserving: these are the same methods the store used to
+ * carry as privates, with the same call order and the same logging. What moved is
+ * where they live, not what they do.
+ * @internal
+ */
+export class VectorMaintenance {
+    constructor(params) {
+        this._vectorIndex = params.vectorIndex;
+        this._embed = params.embed;
+        this._fragmentIndex = params.fragmentIndex;
+        this._fragmentEmbedder = params.fragmentEmbedder;
+        this._warn = params.warn;
+        this._embedsKind = params.embedsKind;
+    }
+    /**
+     * Best-effort removal of everything the two indexes hold for one record. Used
+     * by the delete path and by cull-oldest eviction, both of which have already
+     * committed by the time they call it.
+     */
+    async removeAll(target) {
+        await this._removeVectorBestEffort(target);
+        await this._removeFragmentsBestEffort(target);
+    }
+    /**
+     * Best-effort embed-on-write. When a vector index AND an embedder are wired,
+     * embeds the built record, `add`s the vector (replace semantics handle a same-id
+     * re-embed — no explicit remove), and stamps the returned `embeddingRef`. A
+     * failure (returned `fail` OR a thrown/rejected hook) is logged and the
+     * unembedded record is returned unchanged — the put still persists, and the
+     * derived index is reconciled by a later `rebuild`. A pass-through no-op when
+     * unwired (byte-identical record).
+     *
+     * A **decline** is not a failure and is handled differently: see
+     * `declineEmbedding`.
+     *
+     * Always succeeds (`Result` is the chain's shape, never a vector-induced
+     * failure).
+     */
+    async embedOnWrite(built, scope) {
+        if (this._vectorIndex === undefined || this._embed === undefined) {
+            // No outcome: with nothing wired there is no index for the record to be
+            // absent from, so reporting one would invent a coverage question the
+            // deployment has not asked.
+            return succeed({ record: built });
+        }
+        const vectorIndex = this._vectorIndex;
+        const embed = this._embed;
+        const target = { scope, id: built.envelope.id };
+        // Gate BEFORE the embedder call, which is the whole point: a `MemoryEmbedder`
+        // decline still pays the round trip, and on a locally-hosted model that round
+        // trip IS the cost. A kind excluded here is never handed to the embedder.
+        //
+        // An exclusion reaches the same conclusion as a decline — this record is
+        // intentionally not embedded — so it takes the same path: an inherited
+        // `embeddingRef` is dropped and the vector it named is pruned after the
+        // commit. Otherwise narrowing `embedKinds` on an existing vault would leave
+        // every previously-embedded record of the excluded kind claiming an
+        // embedding the store no longer maintains.
+        if (!this._embedsKind(built.envelope.kind)) {
+            return succeed(declineEmbedding(built, vectorIndex, target, 'excluded'));
+        }
+        const embedded = await this._tryVectorOp(() => embed(built), `embedding '${built.envelope.id}'`);
+        if (embedded.isFailure()) {
+            return succeed({ record: built, embed: 'failed' });
+        }
+        // A deliberate decline (`undefined`) stores the record with no embedding
+        // reference. Deliberately NOT logged, unlike the failure path above: a warning
+        // per write would make routine policy look like a recurring fault, which is
+        // the confusion this return value exists to end. It is still *reported* — as
+        // `embed: 'declined'` on the write observation — because saying nothing at all
+        // is what left `embeddingRef` absence three-ways ambiguous.
+        if (embedded.value === undefined) {
+            return succeed(declineEmbedding(built, vectorIndex, target, 'declined'));
+        }
+        // Hoisted: the `undefined` check above does not narrow across the callback
+        // boundary below, and a local keeps the non-null assertion out of the code.
+        const vector = embedded.value;
+        const added = await this._tryVectorOp(() => vectorIndex.add(target, vector), `vector add for '${built.envelope.id}'`);
+        if (added.isFailure()) {
+            return succeed({ record: built, embed: 'failed' });
+        }
+        return succeed({
+            record: { envelope: Object.assign(Object.assign({}, built.envelope), { embeddingRef: added.value }), body: built.body },
+            embed: 'embedded'
+        });
+    }
+    /**
+     * Prune the vector a decline superseded. Best-effort like the rest of the
+     * vector path: a failed `remove` is logged and the (already-persisted) record
+     * still carries no `embeddingRef`, because the record's own claim about itself
+     * should be true even when the derived index is momentarily stale — that is
+     * exactly what a later `rebuild` reconciles.
+     *
+     * The index travels with the target rather than being re-read from the instance
+     * so the prune lands on the same index the decline was made against, and so
+     * there is no second "is a vector index wired?" check whose false branch cannot
+     * be reached.
+     */
+    async pruneStaleVector(stale) {
+        if (stale === undefined) {
+            return;
+        }
+        await this._tryVectorOp(() => stale.index.remove(stale.target), `vector remove for declined '${stale.target.id}'`);
+    }
+    /**
+     * 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 `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 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 succeed(built);
+        }
+        await this._tryVectorOp(() => fragmentIndex.addFragments(target, embedded.value), `fragment add for '${built.envelope.id}'`);
+        return 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}'`);
+    }
+    /**
+     * Best-effort vector removal for each evicted record (never fails the put).
+     * Every evicted record is in the same `scope` as the incoming write (the
+     * cull-oldest cohort is the incoming record's `(scope, kind)` cohort), so that
+     * scope qualifies each removal target.
+     */
+    async removeEvictedVectors(evicted, scope) {
+        for (const id of evicted) {
+            await this.removeAll({ scope, id });
+        }
+    }
+    /**
+     * Run a consumer-supplied vector hook, normalizing a thrown/rejected hook into a
+     * `Failure` and logging any failure at `warn`. Best-effort: the caller proceeds
+     * regardless, since the index is rebuildable.
+     */
+    async _tryVectorOp(op, label) {
+        let result;
+        try {
+            result = await op();
+        }
+        catch (err) {
+            result = fail(`${label} threw: ${String(err)}`);
+        }
+        if (result.isFailure()) {
+            this._warn(`memory: ${label} failed (best-effort; derived index left for rebuild): ${result.message}`);
+        }
+        return result;
+    }
+    /**
+     * Best-effort vector removal. A no-op unless the full vector lifecycle is wired
+     * (both an index AND an embedder), so an unwired store does no vector work and
+     * behaves byte-identically. Failures are logged, never surfaced — a committed
+     * delete/eviction must not fail because a derived index could not be pruned.
+     */
+    async _removeVectorBestEffort(target) {
+        if (this._vectorIndex === undefined || this._embed === undefined) {
+            return;
+        }
+        const vectorIndex = this._vectorIndex;
+        await this._tryVectorOp(() => vectorIndex.remove(target), `vector removal for '${target.id}'`);
+    }
+}
+//# sourceMappingURL=vectorMaintenance.js.map

package/dist/packlets/store/vectorMaintenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vectorMaintenance.js","sourceRoot":"","sources":["../../../src/packlets/store/vectorMaintenance.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, fail, succeed } from '@fgv/ts-utils';\nimport { MemoryEmbedOutcome } from '../observe';\nimport { IEdgeTarget, IMemoryRecord, Kind, MemoryId, MemoryScopeKey } from '../types';\nimport {\n  FragmentEmbedder,\n  IEmbeddedFragment,\n  IFragmentVectorIndex,\n  IVectorIndex,\n  MemoryEmbedder\n} from '../vector';\n\n/**\n * The internal outcome of record-level embed-on-write: the record to persist,\n * plus — only when the embedder declined a record that already carried an\n * `embeddingRef` — the index entry that reference superseded.\n *\n * `stale` is carried out to the caller rather than acted on in place because the\n * prune belongs on the far side of `_persist`: a persist that fails leaves the\n * PREVIOUS content on disk, and the superseded vector is still an accurate\n * embedding of that content.\n * @internal\n */\nexport interface IEmbedOnWriteOutcome {\n  readonly record: IMemoryRecord<string>;\n  readonly stale?: { readonly index: IVectorIndex; readonly target: IEdgeTarget };\n  /**\n   * What the record-granular index did, surfaced on the write observation.\n   * `undefined` when the question does not apply (nothing wired).\n   */\n  readonly embed?: MemoryEmbedOutcome;\n}\n\n/**\n * Project a record the embedder **declined** into its written form: the same\n * record with no `embeddingRef`, plus the vector (if any) that reference\n * superseded, for the caller to prune after the commit.\n *\n * @remarks\n * A decline says \"this record is intentionally not embedded\". A re-put of a\n * record that *was* embedded (or a caller who supplied an `embeddingRef` — the\n * field is store-derived by contract but nothing strips it) arrives here\n * carrying an inherited reference, so returning it unchanged would persist\n * `embeddingRef` on a record the store just decided not to embed.\n *\n * Clearing the reference alone would be cosmetic and arguably worse: the index\n * entry keyed on this target would survive, so a semantic query would keep\n * returning the record — scored on its **previous** content — while the record\n * itself claimed not to be indexed. So the vector goes too, via\n * `pruneStaleVector` once the write has committed.\n * `stale` is set only when a reference was actually inherited, which keeps the\n * common decline (a record that was never embedded) free of an index round\n * trip.\n *\n * Pure and static: the decision needs nothing from the instance, and deferring\n * the index call to the caller is what lets it run on the far side of\n * `_persist`.\n */\nfunction declineEmbedding(\n  built: IMemoryRecord<string>,\n  index: IVectorIndex,\n  target: IEdgeTarget,\n  embed: MemoryEmbedOutcome\n): IEmbedOnWriteOutcome {\n  if (built.envelope.embeddingRef === undefined) {\n    return { record: built, embed };\n  }\n  // Rest-spread rather than `embeddingRef: undefined`: the envelope is YAML-\n  // serialized, and an explicitly-undefined key is a serializer-dependent way\n  // to say \"absent\" where dropping the key is not.\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  const { embeddingRef, ...envelope } = built.envelope;\n  return { record: { envelope, body: built.body }, stale: { index, target }, embed };\n}\n\n/**\n * What {@link VectorMaintenance} needs from the store it serves. Every field is\n * the store's own, passed in rather than reached for, so this collaborator holds\n * no reference back to the store and cannot quietly grow one.\n * @internal\n */\nexport interface IVectorMaintenanceParams {\n  readonly vectorIndex?: IVectorIndex;\n  readonly embed?: MemoryEmbedder;\n  readonly fragmentIndex?: IFragmentVectorIndex;\n  readonly fragmentEmbedder?: FragmentEmbedder;\n  /** The store's swallowed-failure logger; every vector fault is best-effort. */\n  readonly warn: (message: string) => void;\n  /**\n   * The store's per-kind record-index participation predicate\n   * (`IMemoryStore.embedsKind`). Passed in rather than re-derived so the store's\n   * declaration and the gate that enforces it cannot disagree.\n   */\n  readonly embedsKind: (kind: Kind) => boolean;\n}\n\n/**\n * The store's record- and fragment-vector maintenance, extracted from\n * {@link FileTreeMemoryStore} as a collaborator.\n *\n * @remarks\n * Everything here is **best-effort by contract**: the durable record store is\n * authoritative and both indexes are derived, rebuildable views, so a failed\n * embed, add or remove is logged and the write still succeeds. Nothing in this\n * class can turn a committed write into a `Failure` — which is exactly why it\n * separates cleanly from the store's write path, where every step is fallible\n * and fatal.\n *\n * The split is behavior-preserving: these are the same methods the store used to\n * carry as privates, with the same call order and the same logging. What moved is\n * where they live, not what they do.\n * @internal\n */\nexport class VectorMaintenance {\n  private readonly _vectorIndex: IVectorIndex | undefined;\n  private readonly _embed: MemoryEmbedder | undefined;\n  private readonly _fragmentIndex: IFragmentVectorIndex | undefined;\n  private readonly _fragmentEmbedder: FragmentEmbedder | undefined;\n  private readonly _warn: (message: string) => void;\n  private readonly _embedsKind: (kind: Kind) => boolean;\n\n  public constructor(params: IVectorMaintenanceParams) {\n    this._vectorIndex = params.vectorIndex;\n    this._embed = params.embed;\n    this._fragmentIndex = params.fragmentIndex;\n    this._fragmentEmbedder = params.fragmentEmbedder;\n    this._warn = params.warn;\n    this._embedsKind = params.embedsKind;\n  }\n\n  /**\n   * Best-effort removal of everything the two indexes hold for one record. Used\n   * by the delete path and by cull-oldest eviction, both of which have already\n   * committed by the time they call it.\n   */\n  public async removeAll(target: IEdgeTarget): Promise<void> {\n    await this._removeVectorBestEffort(target);\n    await this._removeFragmentsBestEffort(target);\n  }\n\n  /**\n   * Best-effort embed-on-write. When a vector index AND an embedder are wired,\n   * embeds the built record, `add`s the vector (replace semantics handle a same-id\n   * re-embed — no explicit remove), and stamps the returned `embeddingRef`. A\n   * failure (returned `fail` OR a thrown/rejected hook) is logged and the\n   * unembedded record is returned unchanged — the put still persists, and the\n   * derived index is reconciled by a later `rebuild`. A pass-through no-op when\n   * unwired (byte-identical record).\n   *\n   * A **decline** is not a failure and is handled differently: see\n   * `declineEmbedding`.\n   *\n   * Always succeeds (`Result` is the chain's shape, never a vector-induced\n   * failure).\n   */\n  public async embedOnWrite(\n    built: IMemoryRecord<string>,\n    scope: MemoryScopeKey\n  ): Promise<Result<IEmbedOnWriteOutcome>> {\n    if (this._vectorIndex === undefined || this._embed === undefined) {\n      // No outcome: with nothing wired there is no index for the record to be\n      // absent from, so reporting one would invent a coverage question the\n      // deployment has not asked.\n      return succeed({ record: built });\n    }\n    const vectorIndex: IVectorIndex = this._vectorIndex;\n    const embed: MemoryEmbedder = this._embed;\n    const target: IEdgeTarget = { scope, id: built.envelope.id };\n    // Gate BEFORE the embedder call, which is the whole point: a `MemoryEmbedder`\n    // decline still pays the round trip, and on a locally-hosted model that round\n    // trip IS the cost. A kind excluded here is never handed to the embedder.\n    //\n    // An exclusion reaches the same conclusion as a decline — this record is\n    // intentionally not embedded — so it takes the same path: an inherited\n    // `embeddingRef` is dropped and the vector it named is pruned after the\n    // commit. Otherwise narrowing `embedKinds` on an existing vault would leave\n    // every previously-embedded record of the excluded kind claiming an\n    // embedding the store no longer maintains.\n    if (!this._embedsKind(built.envelope.kind)) {\n      return succeed(declineEmbedding(built, vectorIndex, target, 'excluded'));\n    }\n    const embedded: Result<Float32Array | undefined> = await this._tryVectorOp(\n      () => embed(built),\n      `embedding '${built.envelope.id}'`\n    );\n    if (embedded.isFailure()) {\n      return succeed({ record: built, embed: 'failed' });\n    }\n    // A deliberate decline (`undefined`) stores the record with no embedding\n    // reference. Deliberately NOT logged, unlike the failure path above: a warning\n    // per write would make routine policy look like a recurring fault, which is\n    // the confusion this return value exists to end. It is still *reported* — as\n    // `embed: 'declined'` on the write observation — because saying nothing at all\n    // is what left `embeddingRef` absence three-ways ambiguous.\n    if (embedded.value === undefined) {\n      return succeed(declineEmbedding(built, vectorIndex, target, 'declined'));\n    }\n    // Hoisted: the `undefined` check above does not narrow across the callback\n    // boundary below, and a local keeps the non-null assertion out of the code.\n    const vector: Float32Array = embedded.value;\n    const added: Result<string> = await this._tryVectorOp(\n      () => vectorIndex.add(target, vector),\n      `vector add for '${built.envelope.id}'`\n    );\n    if (added.isFailure()) {\n      return succeed({ record: built, embed: 'failed' });\n    }\n    return succeed({\n      record: { envelope: { ...built.envelope, embeddingRef: added.value }, body: built.body },\n      embed: 'embedded'\n    });\n  }\n\n  /**\n   * Prune the vector a decline superseded. Best-effort like the rest of the\n   * vector path: a failed `remove` is logged and the (already-persisted) record\n   * still carries no `embeddingRef`, because the record's own claim about itself\n   * should be true even when the derived index is momentarily stale — that is\n   * exactly what a later `rebuild` reconciles.\n   *\n   * The index travels with the target rather than being re-read from the instance\n   * so the prune lands on the same index the decline was made against, and so\n   * there is no second \"is a vector index wired?\" check whose false branch cannot\n   * be reached.\n   */\n  public async pruneStaleVector(stale: IEmbedOnWriteOutcome['stale']): Promise<void> {\n    if (stale === undefined) {\n      return;\n    }\n    await this._tryVectorOp(\n      () => stale.index.remove(stale.target),\n      `vector remove for declined '${stale.target.id}'`\n    );\n  }\n\n  /**\n   * Best-effort fragment-embed-on-write. When a fragment index AND a fragment\n   * embedder are wired, chunks + embeds the built record and replaces its\n   * fragments in the index (`addFragments` is whole-record-replace, so a re-authored\n   * document never leaves stale fragments behind — no explicit remove needed). A\n   * failure (returned `fail` OR a thrown/rejected hook) is logged and the record is\n   * returned unchanged — the put still persists, and the fragment index is a derived\n   * view a later `rebuild` reconciles. Unlike `embedOnWrite`\n   * it stamps nothing on the record (fragments have no per-record `embeddingRef`\n   * analog). A pass-through no-op when unwired (byte-identical record).\n   */\n  public async embedFragmentsOnWrite(\n    built: IMemoryRecord<string>,\n    scope: MemoryScopeKey\n  ): Promise<Result<IMemoryRecord<string>>> {\n    if (this._fragmentIndex === undefined || this._fragmentEmbedder === undefined) {\n      return succeed(built);\n    }\n    const fragmentIndex: IFragmentVectorIndex = this._fragmentIndex;\n    const fragmentEmbedder: FragmentEmbedder = this._fragmentEmbedder;\n    const target: IEdgeTarget = { scope, id: built.envelope.id };\n    const embedded: Result<ReadonlyArray<IEmbeddedFragment>> = await this._tryVectorOp(\n      () => fragmentEmbedder(built),\n      `fragment embedding '${built.envelope.id}'`\n    );\n    if (embedded.isFailure()) {\n      return succeed(built);\n    }\n    await this._tryVectorOp(\n      () => fragmentIndex.addFragments(target, embedded.value),\n      `fragment add for '${built.envelope.id}'`\n    );\n    return succeed(built);\n  }\n\n  /**\n   * Best-effort fragment removal. A no-op unless the full fragment lifecycle is\n   * wired (both an index AND an embedder), so an unwired store does no fragment\n   * work and behaves byte-identically. Failures are logged, never surfaced — a\n   * committed delete/eviction must not fail because a derived fragment index could\n   * not be pruned.\n   */\n  private async _removeFragmentsBestEffort(target: IEdgeTarget): Promise<void> {\n    if (this._fragmentIndex === undefined || this._fragmentEmbedder === undefined) {\n      return;\n    }\n    const fragmentIndex: IFragmentVectorIndex = this._fragmentIndex;\n    await this._tryVectorOp(() => fragmentIndex.remove(target), `fragment removal for '${target.id}'`);\n  }\n\n  /**\n   * Best-effort vector removal for each evicted record (never fails the put).\n   * Every evicted record is in the same `scope` as the incoming write (the\n   * cull-oldest cohort is the incoming record's `(scope, kind)` cohort), so that\n   * scope qualifies each removal target.\n   */\n  public async removeEvictedVectors(evicted: ReadonlyArray<MemoryId>, scope: MemoryScopeKey): Promise<void> {\n    for (const id of evicted) {\n      await this.removeAll({ scope, id });\n    }\n  }\n\n  /**\n   * Run a consumer-supplied vector hook, normalizing a thrown/rejected hook into a\n   * `Failure` and logging any failure at `warn`. Best-effort: the caller proceeds\n   * regardless, since the index is rebuildable.\n   */\n  private async _tryVectorOp<T>(op: () => Promise<Result<T>>, label: string): Promise<Result<T>> {\n    let result: Result<T>;\n    try {\n      result = await op();\n    } catch (err) {\n      result = fail(`${label} threw: ${String(err)}`);\n    }\n    if (result.isFailure()) {\n      this._warn(`memory: ${label} failed (best-effort; derived index left for rebuild): ${result.message}`);\n    }\n    return result;\n  }\n\n  /**\n   * Best-effort vector removal. A no-op unless the full vector lifecycle is wired\n   * (both an index AND an embedder), so an unwired store does no vector work and\n   * behaves byte-identically. Failures are logged, never surfaced — a committed\n   * delete/eviction must not fail because a derived index could not be pruned.\n   */\n  private async _removeVectorBestEffort(target: IEdgeTarget): Promise<void> {\n    if (this._vectorIndex === undefined || this._embed === undefined) {\n      return;\n    }\n    const vectorIndex: IVectorIndex = this._vectorIndex;\n    await this._tryVectorOp(() => vectorIndex.remove(target), `vector removal for '${target.id}'`);\n  }\n}\n"]}

package/dist/packlets/types/envelope.js.map

@@ -1 +1 @@
-{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../../src/packlets/types/envelope.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAyDH;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,MAAmB;IAC/C,OAAO,GAAG,MAAM,CAAC,KAAK,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC;AACzC,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { EntityId, Kind, LinkType, MemoryId, MemoryScopeKey, Tag } from './ids';\n\n/**\n * Origin of a provenance attribution. Open vocabulary: the three named\n * sources are conventional, but the `(string & {})` arm admits any other\n * source string without resignature.\n * @public\n */\nexport type ProvenanceSource = 'agent' | 'host-ingest' | 'human' | (string & {});\n\n/**\n * Structured provenance for a record or an edge. Never a flat enum — the\n * `[key: string]: unknown` index signature lets a consumer attach an opaque\n * domain payload (e.g. PersonAIlity's sentiment / epistemic blocks) without\n * changing this interface, while still satisfying the no-`any` rule.\n * @public\n */\nexport interface IProvenance {\n  /** Where the attribution came from. */\n  readonly source: ProvenanceSource;\n  /** Optional human or agent identifier responsible for the write. */\n  readonly by?: string;\n  /** Optional model identifier, when a model produced the content. */\n  readonly model?: string;\n  /** Optional confidence in `[0, 1]`. */\n  readonly confidence?: number;\n  /**\n   * Scope-qualified back-link to the source record. Enables the cross-kind\n   * provenance spine. A scope-qualified {@link IEdgeTarget} (not a bare\n   * {@link MemoryId}) because per-scope codecs (e.g. the MTM codec's `turn-<n>`\n   * stems) legally reuse a stem across scopes, so a bare id would be ambiguous —\n   * the same reason {@link IEdge.target} is scope-qualified.\n   */\n  readonly derivedFrom?: IEdgeTarget;\n  /** Opaque extension payload — consumer-owned, never interpreted by the store. */\n  readonly [key: string]: unknown;\n}\n\n/**\n * The physical address of a linked-to record: the `(scope, id)` pair that\n * uniquely identifies it. Both components are required because a bare\n * {@link MemoryId} is NOT unique across scopes — per-scope codecs (e.g. the\n * medium-term codec's `turn-<n>` stems) legally mint the same stem under\n * different scopes, so an edge that carried only the id would be ambiguous.\n * `(scope, id)` matches the store's `getById(scope, id)` addressing and the\n * index's composite primary key.\n * @public\n */\nexport interface IEdgeTarget {\n  /** The scope the target record lives under. */\n  readonly scope: MemoryScopeKey;\n  /** The target record's stable file-stem id (unique WITHIN {@link IEdgeTarget.scope}). */\n  readonly id: MemoryId;\n}\n\n/**\n * The canonical composite-key string for an {@link IEdgeTarget}: scope + id,\n * NUL-separated. NUL is excluded from both components (scope segments are\n * filename-safe; {@link MemoryId} is portable-filename-safe), so it is a\n * collision-proof separator. This is the ONE canonicalization every consumer\n * that keys on a scoped target uses — the backlink index, the cycle guard, and\n * the ingest edge-validation path all route through it so their notions of\n * \"same target\" cannot drift.\n * @public\n */\nexport function edgeTargetKey(target: IEdgeTarget): string {\n  return `${target.scope}\\0${target.id}`;\n}\n\n/**\n * An attributed link between two records. Carries the relation type, the\n * scope-qualified {@link IEdgeTarget | target}, and optional confidence /\n * provenance / world-truth validity. Replaces bare string references (e.g.\n * PersonAIlity's `IMtmRef` becomes an `IEdge` with `type: LinkType('mtm-ref')`).\n * @public\n */\nexport interface IEdge {\n  /** Open-vocabulary relation type. */\n  readonly type: LinkType;\n  /** The scope-qualified address of the linked-to record. */\n  readonly target: IEdgeTarget;\n  /** Optional confidence in `[0, 1]`. */\n  readonly confidence?: number;\n  /** Optional structured provenance for the link itself. */\n  readonly provenance?: IProvenance;\n  /** World-truth validity start (epoch ms). Present only on temporal edges. */\n  readonly valid_at?: number;\n  /**\n   * World-truth validity end (epoch ms). `null` = still valid; absent = no\n   * temporal extent.\n   */\n  // eslint-disable-next-line @rushstack/no-new-null -- null is a meaningful value here (still-valid) distinct from absent (no temporal extent); design-lock §2.3\n  readonly invalid_at?: number | null;\n}\n\n/**\n * Optional bi-temporal validity block on an envelope. Present only on\n * temporal kinds; absent = zero cost for atemporal kinds.\n * @public\n */\nexport interface ITemporalBlock {\n  /** World-truth validity start (epoch ms). */\n  readonly valid_at?: number;\n  /** World-truth validity end (epoch ms). `null` = still valid. */\n  // eslint-disable-next-line @rushstack/no-new-null -- null is a meaningful value here (still-valid) distinct from absent; design-lock §2.4\n  readonly invalid_at?: number | null;\n}\n\n/**\n * The invariant identity + transaction-time envelope carried by every memory\n * record, independent of the per-kind body.\n * @public\n */\nexport interface IMemoryEnvelope {\n  // --- Core identity ---\n  /** Stable file-stem identifier. MUST equal the on-disk filename stem. */\n  readonly id: MemoryId;\n  /** Consumer-supplied domain key. Equals {@link IMemoryEnvelope.id | id} for non-temporal kinds. */\n  readonly entityId: EntityId;\n  /** Consumer-registered kind; dispatches the body Converter. */\n  readonly kind: Kind;\n  /** Open-vocabulary tags. */\n  readonly tags: ReadonlyArray<Tag>;\n  /** Attributed outbound edges. */\n  readonly links: ReadonlyArray<IEdge>;\n\n  // --- Transaction-time metadata (always present) ---\n  /** Epoch ms of the first write. Immutable after creation. */\n  readonly created: number;\n  /** Epoch ms of the most recent write. */\n  readonly updated: number;\n  /**\n   * Monotonic write counter within the store instance, assigned by the store\n   * on every successful put. Enables stable cursor paging over observation\n   * records without a full walk.\n   */\n  readonly seq: number;\n  /**\n   * Content hash over the canonical `{ kind, body, links }`. The dedup key:\n   * an exact match is a no-op upsert that returns the existing record.\n   */\n  readonly contentHash: string;\n  /**\n   * Store-computed host-defined ordering value, produced by the kind's\n   * {@link RankProjector} on every put/update and stamped into the envelope in\n   * the same pass that recomputes {@link IMemoryEnvelope.contentHash | contentHash}.\n   * Absent when the kind has no registered projector (or the projector threw on\n   * this record). Ordered retrieval (`orderBy: 'rank'`) and the index's rank view\n   * sort by this value descending, placing records with an absent `rank` last.\n   */\n  readonly rank?: number;\n  /** Structured provenance (never a flat enum). */\n  readonly provenance: IProvenance;\n\n  // --- Optional temporal block ---\n  /** Bi-temporal validity. Present only on temporal kinds. */\n  readonly temporal?: ITemporalBlock;\n\n  /**\n   * Vector-index entry reference, set by the vector index on write. `null` =\n   * not embedded; absent = same as `null` (backwards-compat seam).\n   */\n  // eslint-disable-next-line @rushstack/no-new-null -- null is the explicit \"not embedded\" sentinel distinct from absent (backwards-compat seam); design-lock §2.5\n  readonly embeddingRef?: string | null;\n}\n\n/**\n * A complete memory record: the invariant {@link IMemoryEnvelope} plus the\n * typed, per-kind body. The store's public surface uses\n * `IMemoryRecord<unknown>`; consumers narrow `TBody` by checking\n * `envelope.kind` and validating through the registered Converter.\n * @public\n */\nexport interface IMemoryRecord<TBody = unknown> {\n  /** The invariant identity + transaction-time envelope. */\n  readonly envelope: IMemoryEnvelope;\n  /** The per-kind, Converter-validated body. */\n  readonly body: TBody;\n}\n\n/**\n * A per-kind host projection from a fully-resolved (post-merge) memory record\n * to a numeric ordering value. Registered per kind at store construction (see\n * `rankProjectors`); the store runs it on every put/update over the same\n * resolved record whose `contentHash` it computes, stamping the result into\n * {@link IMemoryEnvelope.rank}. The store never interprets the body — the host\n * owns what the number means. A projector that throws is treated as \"no rank\n * for this record\" (logged at `warn`), never failing the write.\n * @public\n */\nexport type RankProjector = (record: IMemoryRecord<unknown>) => number;\n"]}
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../../src/packlets/types/envelope.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAyDH;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,MAAmB;IAC/C,OAAO,GAAG,MAAM,CAAC,KAAK,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC;AACzC,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { EntityId, Kind, LinkType, MemoryId, MemoryScopeKey, Tag } from './ids';\n\n/**\n * Origin of a provenance attribution. Open vocabulary: the three named\n * sources are conventional, but the `(string & {})` arm admits any other\n * source string without resignature.\n * @public\n */\nexport type ProvenanceSource = 'agent' | 'host-ingest' | 'human' | (string & {});\n\n/**\n * Structured provenance for a record or an edge. Never a flat enum — the\n * `[key: string]: unknown` index signature lets a consumer attach an opaque\n * domain payload (e.g. PersonAIlity's sentiment / epistemic blocks) without\n * changing this interface, while still satisfying the no-`any` rule.\n * @public\n */\nexport interface IProvenance {\n  /** Where the attribution came from. */\n  readonly source: ProvenanceSource;\n  /** Optional human or agent identifier responsible for the write. */\n  readonly by?: string;\n  /** Optional model identifier, when a model produced the content. */\n  readonly model?: string;\n  /** Optional confidence in `[0, 1]`. */\n  readonly confidence?: number;\n  /**\n   * Scope-qualified back-link to the source record. Enables the cross-kind\n   * provenance spine. A scope-qualified {@link IEdgeTarget} (not a bare\n   * {@link MemoryId}) because per-scope codecs (e.g. the MTM codec's `turn-<n>`\n   * stems) legally reuse a stem across scopes, so a bare id would be ambiguous —\n   * the same reason {@link IEdge.target} is scope-qualified.\n   */\n  readonly derivedFrom?: IEdgeTarget;\n  /** Opaque extension payload — consumer-owned, never interpreted by the store. */\n  readonly [key: string]: unknown;\n}\n\n/**\n * The physical address of a linked-to record: the `(scope, id)` pair that\n * uniquely identifies it. Both components are required because a bare\n * {@link MemoryId} is NOT unique across scopes — per-scope codecs (e.g. the\n * medium-term codec's `turn-<n>` stems) legally mint the same stem under\n * different scopes, so an edge that carried only the id would be ambiguous.\n * `(scope, id)` matches the store's `getById(scope, id)` addressing and the\n * index's composite primary key.\n * @public\n */\nexport interface IEdgeTarget {\n  /** The scope the target record lives under. */\n  readonly scope: MemoryScopeKey;\n  /** The target record's stable file-stem id (unique WITHIN {@link IEdgeTarget.scope}). */\n  readonly id: MemoryId;\n}\n\n/**\n * The canonical composite-key string for an {@link IEdgeTarget}: scope + id,\n * NUL-separated. NUL is excluded from both components (scope segments are\n * filename-safe; {@link MemoryId} is portable-filename-safe), so it is a\n * collision-proof separator. This is the ONE canonicalization every consumer\n * that keys on a scoped target uses — the backlink index, the cycle guard, and\n * the ingest edge-validation path all route through it so their notions of\n * \"same target\" cannot drift.\n * @public\n */\nexport function edgeTargetKey(target: IEdgeTarget): string {\n  return `${target.scope}\\0${target.id}`;\n}\n\n/**\n * An attributed link between two records. Carries the relation type, the\n * scope-qualified {@link IEdgeTarget | target}, and optional confidence /\n * provenance / world-truth validity. Replaces bare string references (e.g.\n * PersonAIlity's `IMtmRef` becomes an `IEdge` with `type: LinkType('mtm-ref')`).\n * @public\n */\nexport interface IEdge {\n  /** Open-vocabulary relation type. */\n  readonly type: LinkType;\n  /** The scope-qualified address of the linked-to record. */\n  readonly target: IEdgeTarget;\n  /** Optional confidence in `[0, 1]`. */\n  readonly confidence?: number;\n  /** Optional structured provenance for the link itself. */\n  readonly provenance?: IProvenance;\n  /** World-truth validity start (epoch ms). Present only on temporal edges. */\n  readonly valid_at?: number;\n  /**\n   * World-truth validity end (epoch ms). `null` = still valid; absent = no\n   * temporal extent.\n   */\n  // eslint-disable-next-line @rushstack/no-new-null -- null is a meaningful value here (still-valid) distinct from absent (no temporal extent); design-lock §2.3\n  readonly invalid_at?: number | null;\n}\n\n/**\n * Optional bi-temporal validity block on an envelope. Present only on\n * temporal kinds; absent = zero cost for atemporal kinds.\n * @public\n */\nexport interface ITemporalBlock {\n  /** World-truth validity start (epoch ms). */\n  readonly valid_at?: number;\n  /** World-truth validity end (epoch ms). `null` = still valid. */\n  // eslint-disable-next-line @rushstack/no-new-null -- null is a meaningful value here (still-valid) distinct from absent; design-lock §2.4\n  readonly invalid_at?: number | null;\n}\n\n/**\n * The invariant identity + transaction-time envelope carried by every memory\n * record, independent of the per-kind body.\n * @public\n */\nexport interface IMemoryEnvelope {\n  // --- Core identity ---\n  /** Stable file-stem identifier. MUST equal the on-disk filename stem. */\n  readonly id: MemoryId;\n  /** Consumer-supplied domain key. Equals {@link IMemoryEnvelope.id | id} for non-temporal kinds. */\n  readonly entityId: EntityId;\n  /** Consumer-registered kind; dispatches the body Converter. */\n  readonly kind: Kind;\n  /** Open-vocabulary tags. */\n  readonly tags: ReadonlyArray<Tag>;\n  /** Attributed outbound edges. */\n  readonly links: ReadonlyArray<IEdge>;\n\n  // --- Transaction-time metadata (always present) ---\n  /** Epoch ms of the first write. Immutable after creation. */\n  readonly created: number;\n  /** Epoch ms of the most recent write. */\n  readonly updated: number;\n  /**\n   * Monotonic write counter within the store instance, assigned by the store\n   * on every successful put. Enables stable cursor paging over observation\n   * records without a full walk.\n   */\n  readonly seq: number;\n  /**\n   * Content hash over the canonical `{ kind, body, links }`. The dedup key:\n   * an exact match is a no-op upsert that returns the existing record.\n   */\n  readonly contentHash: string;\n  /**\n   * Store-computed host-defined ordering value, produced by the kind's\n   * {@link RankProjector} on every put/update and stamped into the envelope in\n   * the same pass that recomputes {@link IMemoryEnvelope.contentHash | contentHash}.\n   * Absent when the kind has no registered projector (or the projector threw on\n   * this record). Ordered retrieval (`orderBy: 'rank'`) and the index's rank view\n   * sort by this value descending, placing records with an absent `rank` last.\n   *\n   * **The projector runs on the write path only — registering one does not rank\n   * records already in the store.** Because absent sorts last, those records land\n   * below every subsequently-written one regardless of what the projector would\n   * have scored them, so the result is not a partial ordering but one inverted\n   * with respect to the projector's intent, with nothing failing to say so. Call\n   * `IMemoryStore.reconcileRank` after registering a projector against a\n   * populated store.\n   */\n  readonly rank?: number;\n  /** Structured provenance (never a flat enum). */\n  readonly provenance: IProvenance;\n\n  // --- Optional temporal block ---\n  /** Bi-temporal validity. Present only on temporal kinds. */\n  readonly temporal?: ITemporalBlock;\n\n  /**\n   * Vector-index entry reference, set by the vector index on write. `null` =\n   * not embedded; absent = same as `null` (backwards-compat seam).\n   */\n  // eslint-disable-next-line @rushstack/no-new-null -- null is the explicit \"not embedded\" sentinel distinct from absent (backwards-compat seam); design-lock §2.5\n  readonly embeddingRef?: string | null;\n}\n\n/**\n * A complete memory record: the invariant {@link IMemoryEnvelope} plus the\n * typed, per-kind body. The store's public surface uses\n * `IMemoryRecord<unknown>`; consumers narrow `TBody` by checking\n * `envelope.kind` and validating through the registered Converter.\n * @public\n */\nexport interface IMemoryRecord<TBody = unknown> {\n  /** The invariant identity + transaction-time envelope. */\n  readonly envelope: IMemoryEnvelope;\n  /** The per-kind, Converter-validated body. */\n  readonly body: TBody;\n}\n\n/**\n * A per-kind host projection from a fully-resolved (post-merge) memory record\n * to a numeric ordering value. Registered per kind at store construction (see\n * `rankProjectors`); the store runs it on every put/update over the same\n * resolved record whose `contentHash` it computes, stamping the result into\n * {@link IMemoryEnvelope.rank}. The store never interprets the body — the host\n * owns what the number means. A projector that throws is treated as \"no rank\n * for this record\" (logged at `warn`), never failing the write.\n *\n * Runs on writes only. To apply a newly-registered projector to records that\n * already exist, call `IMemoryStore.reconcileRank`.\n * @public\n */\nexport type RankProjector = (record: IMemoryRecord<unknown>) => number;\n"]}

package/dist/packlets/vector/inMemoryCosineIndex.js

@@ -2,8 +2,17 @@
  * Copyright (c) 2026 Erik Fortune
  * SPDX-License-Identifier: MIT
  */
-import { fail, succeed } from '@fgv/ts-utils';
+import { captureAsyncResult, fail, succeed } from '@fgv/ts-utils';
 import { edgeTargetKey } from '../types';
+/**
+ * Invoke a consumer-supplied hook that already returns a `Result`, converting a
+ * synchronous throw or a promise rejection into a `Failure` rather than letting
+ * it escape. `captureAsyncResult` wraps the hook's own `Result`, so the outcome
+ * is flattened back to one level.
+ */
+async function invokeHook(hook) {
+    return (await captureAsyncResult(hook)).onSuccess((inner) => inner);
+}
 /**
  * The brute-force, in-memory cosine {@link IVectorIndex}. Stores one
  * `Float32Array` per record and answers a query by computing cosine similarity
@@ -88,38 +97,92 @@ export class InMemoryCosineIndex {
     /**
      * Re-embed every record from `source` and rebuild the index from scratch.
      * Clears the current contents (and the established dimension) first, so a
-     * re-embed with a different model is supported. Returns the number of vectors
-     * indexed.
+     * re-embed with a different model is supported. Returns an
+     * {@link IVectorRebuildReport} describing what was indexed, declined and skipped.
+     *
+     * @remarks
+     * **A failure to LIST is always fatal**, under either mode — and **leaves the
+     * existing index untouched**: an unreadable source says nothing about which
+     * records exist, so there is neither an honest partial to report nor any reason
+     * to discard what is already held.
+     *
+     * Per-record embed/add failures are governed by
+     * {@link IVectorRebuildOptions.onRecordError}, which defaults to `'fail'` —
+     * **the historical all-or-nothing contract, unchanged**: the index is rolled back
+     * to empty rather than left partially rebuilt, so a caller that retries a query
+     * sees a clean empty index it can reason about.
      *
-     * On any failure (list, embed, or add) the index is rolled back to empty
-     * rather than left in a partially-rebuilt state — a caller that retries a query
-     * after a failed rebuild sees a clean empty index, never a half-populated one.
+     * `'skip'` opts into the lenient shape the store's own open already uses: the
+     * rebuild continues and every casualty is returned structurally on
+     * {@link IVectorRebuildReport.skipped}. **It reports more, it does not report
+     * less** — the point is to stop one bad record emptying an entire index, not to
+     * make failures quieter. A caller that ignores `skipped` under `'skip'` has
+     * chosen to, rather than been given no way to know.
+     *
+     * A {@link MemoryEmbedder} decline is not a failure under either mode: it is
+     * counted on {@link IVectorRebuildReport.declined} and never appears in `skipped`.
+     *
+     * Both consumer-supplied hooks are capture-wrapped, so a `source` or `embed`
+     * that throws or rejects becomes a `Failure` on the path above rather than an
+     * exception escaping mid-rebuild — which would bypass the rollback entirely.
      *
      * @param source - The scope-qualified record source to re-embed.
      * @param embed - The embedder applied to each record.
+     * @param options - Rebuild options; omit for the historical `'fail'` behavior.
      */
-    async rebuild(source, embed) {
-        // Reset up front so the "any failure leaves the index empty" contract holds
-        // even when the listing itself fails (no stale vectors survive a failed
-        // rebuild).
-        this._reset();
-        const listed = await source.list();
+    async rebuild(source, embed, options) {
+        var _a;
+        const lenient = ((_a = options === null || options === void 0 ? void 0 : options.onRecordError) !== null && _a !== void 0 ? _a : 'fail') === 'skip';
+        const listed = await invokeHook(() => source.list());
         if (listed.isFailure()) {
+            // Deliberately BEFORE the reset. This used to reset first, on the reasoning
+            // that no stale vectors should survive a failed rebuild — but a failed list
+            // is no evidence about the vectors already held, and nothing has been
+            // re-embedded yet, so there is no half-rebuilt state to guard against.
+            // Leaving the prior contents intact is the more correct answer, and on the
+            // durable sibling (`SqliteVecVectorIndex`) resetting here was data loss.
             return fail(`vector index rebuild: failed to list records: ${listed.message}`);
         }
+        // From here a rebuild is genuinely starting, so clear. A mid-loop failure
+        // under `'fail'` still resets, which is what keeps that contract honest.
+        this._reset();
+        let declined = 0;
+        const skipped = [];
         for (const scoped of listed.value) {
-            const embedded = await embed(scoped.record);
+            // Both hooks are consumer-supplied, so a throw or rejection is captured
+            // into a `Failure` rather than escaping as an exception — otherwise a
+            // badly-behaved embedder would reject out of `rebuild` mid-loop and leave
+            // the index half-populated, which is precisely what the rollback below
+            // exists to prevent.
+            const embedded = await invokeHook(() => embed(scoped.record));
             if (embedded.isFailure()) {
-                this._reset();
-                return fail(`vector index rebuild: embedding '${edgeTargetKey(scoped.target)}' failed: ${embedded.message}`);
+                const error = `vector index rebuild: embedding '${edgeTargetKey(scoped.target)}' failed: ${embedded.message}`;
+                // `'fail'` keeps the historical all-or-nothing contract EXACTLY: reset and
+                // abort, so a caller that retries a query sees a clean empty index rather
+                // than a partially-rebuilt one it cannot reason about.
+                if (!lenient) {
+                    this._reset();
+                    return fail(error);
+                }
+                skipped.push({ target: scoped.target, error });
+                continue;
+            }
+            // A decline is not an error under either mode — it is counted, never skipped.
+            if (embedded.value === undefined) {
+                declined++;
+                continue;
             }
             const added = await this.add(scoped.target, embedded.value);
             if (added.isFailure()) {
-                this._reset();
-                return fail(`vector index rebuild: ${added.message}`);
+                const error = `vector index rebuild: ${added.message}`;
+                if (!lenient) {
+                    this._reset();
+                    return fail(error);
+                }
+                skipped.push({ target: scoped.target, error });
             }
         }
-        return succeed(this._vectors.size);
+        return succeed({ indexed: this._vectors.size, declined, skipped });
     }
     /** Empty the index and forget the established dimension. */
     _reset() {

package/dist/packlets/vector/inMemoryCosineIndex.js.map

@@ -1 +1 @@
-{"version":3,"file":"inMemoryCosineIndex.js","sourceRoot":"","sources":["../../../src/packlets/vector/inMemoryCosineIndex.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, fail, succeed } from '@fgv/ts-utils';\nimport { IEdgeTarget, edgeTargetKey } from '../types';\nimport {\n  IMemoryRecordSource,\n  IScopedMemoryRecord,\n  IVectorIndex,\n  IVectorQueryHit,\n  MemoryEmbedder\n} from './vectorIndex';\n\n/** One stored embedding: the scope-qualified address plus its vector. */\ninterface IStoredVector {\n  readonly target: IEdgeTarget;\n  readonly vector: Float32Array;\n}\n\n/**\n * The brute-force, in-memory cosine {@link IVectorIndex}. Stores one\n * `Float32Array` per record and answers a query by computing cosine similarity\n * against every stored vector, returning the top-k by descending score.\n *\n * @remarks\n * This is the **complete** vector implementation for the fgv regime — large-N is\n * explicitly out of scope (the seam stays open for a consumer to swap an external\n * ANN backend once N grows beyond \"thousands of records\"). No external dependency\n * and no ANN structure: a linear scan over a few thousand vectors is well within\n * an interactive budget.\n *\n * The index has a single dimension established by the first vector added; every\n * subsequent `add` and every `query` vector must match that dimension or fail\n * loudly — a mismatched dimension is an embedder-wiring bug, never a silent\n * zero-similarity result. {@link InMemoryCosineIndex.rebuild | rebuild} clears\n * the index, so a re-embed with a different model (hence dimension) is supported.\n *\n * Persistence (a JSON sidecar) is deliberately out of scope for this layer — the\n * index is in-memory and rebuilt from the store via `rebuild`; a sidecar is a\n * future nicety.\n * @public\n */\nexport class InMemoryCosineIndex implements IVectorIndex {\n  /**\n   * Stored embeddings keyed by the canonical {@link edgeTargetKey} of the\n   * record's scope-qualified address, so two records that share a filename stem\n   * across scopes occupy distinct entries and never overwrite each other.\n   */\n  private readonly _vectors: Map<string, IStoredVector>;\n  /** The dimension of every stored vector; `undefined` until the first `add`. */\n  private _dimension: number | undefined;\n\n  private constructor() {\n    this._vectors = new Map<string, IStoredVector>();\n    this._dimension = undefined;\n  }\n\n  /** The number of vectors currently held. */\n  public get size(): number {\n    return this._vectors.size;\n  }\n\n  /** Family-convention factory. */\n  public static create(): Result<InMemoryCosineIndex> {\n    return succeed(new InMemoryCosineIndex());\n  }\n\n  /** {@inheritDoc IVectorIndex.add} */\n  public add(target: IEdgeTarget, vector: Float32Array): Promise<Result<string>> {\n    const key: string = edgeTargetKey(target);\n    if (vector.length === 0) {\n      return Promise.resolve(fail(`vector index: cannot add '${key}': empty vector`));\n    }\n    if (this._dimension === undefined) {\n      this._dimension = vector.length;\n    } else if (vector.length !== this._dimension) {\n      return Promise.resolve(\n        fail(\n          `vector index: cannot add '${key}': dimension ${vector.length} does not match index dimension ${this._dimension}`\n        )\n      );\n    }\n    // Defensive copy: the caller may reuse or mutate the buffer after `add`, and\n    // the index must keep serving the embedding it was given.\n    this._vectors.set(key, { target, vector: Float32Array.from(vector) });\n    // The in-memory index keys entries by the canonical scoped-target string, so\n    // that key IS the entry reference.\n    return Promise.resolve(succeed(key));\n  }\n\n  /** {@inheritDoc IVectorIndex.remove} */\n  public remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>> {\n    this._vectors.delete(edgeTargetKey(target));\n    return Promise.resolve(succeed(target));\n  }\n\n  /** {@inheritDoc IVectorIndex.query} */\n  public query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>> {\n    if (topK <= 0 || this._vectors.size === 0) {\n      return Promise.resolve(succeed([]));\n    }\n    if (vector.length !== this._dimension) {\n      return Promise.resolve(\n        fail(\n          `vector index: query dimension ${vector.length} does not match index dimension ${this._dimension}`\n        )\n      );\n    }\n    const queryMagnitude: number = InMemoryCosineIndex._magnitude(vector);\n    const hits: IVectorQueryHit[] = [];\n    for (const stored of this._vectors.values()) {\n      hits.push({\n        target: stored.target,\n        score: InMemoryCosineIndex._cosine(vector, queryMagnitude, stored.vector)\n      });\n    }\n    // Descending by score; a `seq`-free tiebreak is unnecessary here because the\n    // caller (SemanticRetriever) re-resolves hits against the record index.\n    hits.sort((a, b) => b.score - a.score);\n    return Promise.resolve(succeed(hits.length > topK ? hits.slice(0, topK) : hits));\n  }\n\n  /**\n   * Re-embed every record from `source` and rebuild the index from scratch.\n   * Clears the current contents (and the established dimension) first, so a\n   * re-embed with a different model is supported. Returns the number of vectors\n   * indexed.\n   *\n   * On any failure (list, embed, or add) the index is rolled back to empty\n   * rather than left in a partially-rebuilt state — a caller that retries a query\n   * after a failed rebuild sees a clean empty index, never a half-populated one.\n   *\n   * @param source - The scope-qualified record source to re-embed.\n   * @param embed - The embedder applied to each record.\n   */\n  public async rebuild(source: IMemoryRecordSource, embed: MemoryEmbedder): Promise<Result<number>> {\n    // Reset up front so the \"any failure leaves the index empty\" contract holds\n    // even when the listing itself fails (no stale vectors survive a failed\n    // rebuild).\n    this._reset();\n    const listed: Result<ReadonlyArray<IScopedMemoryRecord>> = await source.list();\n    if (listed.isFailure()) {\n      return fail(`vector index rebuild: failed to list records: ${listed.message}`);\n    }\n    for (const scoped of listed.value) {\n      const embedded: Result<Float32Array> = await embed(scoped.record);\n      if (embedded.isFailure()) {\n        this._reset();\n        return fail(\n          `vector index rebuild: embedding '${edgeTargetKey(scoped.target)}' failed: ${embedded.message}`\n        );\n      }\n      const added: Result<string> = await this.add(scoped.target, embedded.value);\n      if (added.isFailure()) {\n        this._reset();\n        return fail(`vector index rebuild: ${added.message}`);\n      }\n    }\n    return succeed(this._vectors.size);\n  }\n\n  /** Empty the index and forget the established dimension. */\n  private _reset(): void {\n    this._vectors.clear();\n    this._dimension = undefined;\n  }\n\n  /** The Euclidean magnitude (L2 norm) of a vector. */\n  private static _magnitude(vector: Float32Array): number {\n    let sum: number = 0;\n    for (let i: number = 0; i < vector.length; i++) {\n      sum += vector[i] * vector[i];\n    }\n    return Math.sqrt(sum);\n  }\n\n  /**\n   * Cosine similarity between the query (whose magnitude is precomputed once and\n   * reused across the scan) and a stored vector. A zero-magnitude vector on\n   * either side yields `0` rather than `NaN` — a degenerate vector is simply\n   * maximally dissimilar, not an error.\n   */\n  private static _cosine(query: Float32Array, queryMagnitude: number, stored: Float32Array): number {\n    const storedMagnitude: number = InMemoryCosineIndex._magnitude(stored);\n    if (queryMagnitude === 0 || storedMagnitude === 0) {\n      return 0;\n    }\n    let dot: number = 0;\n    for (let i: number = 0; i < query.length; i++) {\n      dot += query[i] * stored[i];\n    }\n    return dot / (queryMagnitude * storedMagnitude);\n  }\n}\n"]}
+{"version":3,"file":"inMemoryCosineIndex.js","sourceRoot":"","sources":["../../../src/packlets/vector/inMemoryCosineIndex.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, captureAsyncResult, fail, succeed } from '@fgv/ts-utils';\nimport { IEdgeTarget, edgeTargetKey } from '../types';\nimport {\n  IMemoryRecordSource,\n  IScopedMemoryRecord,\n  ISkippedVectorRecord,\n  IVectorIndex,\n  IVectorQueryHit,\n  IVectorRebuildOptions,\n  IVectorRebuildReport,\n  MemoryEmbedder\n} from './vectorIndex';\n\n/**\n * Invoke a consumer-supplied hook that already returns a `Result`, converting a\n * synchronous throw or a promise rejection into a `Failure` rather than letting\n * it escape. `captureAsyncResult` wraps the hook's own `Result`, so the outcome\n * is flattened back to one level.\n */\nasync function invokeHook<T>(hook: () => Promise<Result<T>>): Promise<Result<T>> {\n  return (await captureAsyncResult(hook)).onSuccess((inner) => inner);\n}\n\n/** One stored embedding: the scope-qualified address plus its vector. */\ninterface IStoredVector {\n  readonly target: IEdgeTarget;\n  readonly vector: Float32Array;\n}\n\n/**\n * The brute-force, in-memory cosine {@link IVectorIndex}. Stores one\n * `Float32Array` per record and answers a query by computing cosine similarity\n * against every stored vector, returning the top-k by descending score.\n *\n * @remarks\n * This is the **complete** vector implementation for the fgv regime — large-N is\n * explicitly out of scope (the seam stays open for a consumer to swap an external\n * ANN backend once N grows beyond \"thousands of records\"). No external dependency\n * and no ANN structure: a linear scan over a few thousand vectors is well within\n * an interactive budget.\n *\n * The index has a single dimension established by the first vector added; every\n * subsequent `add` and every `query` vector must match that dimension or fail\n * loudly — a mismatched dimension is an embedder-wiring bug, never a silent\n * zero-similarity result. {@link InMemoryCosineIndex.rebuild | rebuild} clears\n * the index, so a re-embed with a different model (hence dimension) is supported.\n *\n * Persistence (a JSON sidecar) is deliberately out of scope for this layer — the\n * index is in-memory and rebuilt from the store via `rebuild`; a sidecar is a\n * future nicety.\n * @public\n */\nexport class InMemoryCosineIndex implements IVectorIndex {\n  /**\n   * Stored embeddings keyed by the canonical {@link edgeTargetKey} of the\n   * record's scope-qualified address, so two records that share a filename stem\n   * across scopes occupy distinct entries and never overwrite each other.\n   */\n  private readonly _vectors: Map<string, IStoredVector>;\n  /** The dimension of every stored vector; `undefined` until the first `add`. */\n  private _dimension: number | undefined;\n\n  private constructor() {\n    this._vectors = new Map<string, IStoredVector>();\n    this._dimension = undefined;\n  }\n\n  /** The number of vectors currently held. */\n  public get size(): number {\n    return this._vectors.size;\n  }\n\n  /** Family-convention factory. */\n  public static create(): Result<InMemoryCosineIndex> {\n    return succeed(new InMemoryCosineIndex());\n  }\n\n  /** {@inheritDoc IVectorIndex.add} */\n  public add(target: IEdgeTarget, vector: Float32Array): Promise<Result<string>> {\n    const key: string = edgeTargetKey(target);\n    if (vector.length === 0) {\n      return Promise.resolve(fail(`vector index: cannot add '${key}': empty vector`));\n    }\n    if (this._dimension === undefined) {\n      this._dimension = vector.length;\n    } else if (vector.length !== this._dimension) {\n      return Promise.resolve(\n        fail(\n          `vector index: cannot add '${key}': dimension ${vector.length} does not match index dimension ${this._dimension}`\n        )\n      );\n    }\n    // Defensive copy: the caller may reuse or mutate the buffer after `add`, and\n    // the index must keep serving the embedding it was given.\n    this._vectors.set(key, { target, vector: Float32Array.from(vector) });\n    // The in-memory index keys entries by the canonical scoped-target string, so\n    // that key IS the entry reference.\n    return Promise.resolve(succeed(key));\n  }\n\n  /** {@inheritDoc IVectorIndex.remove} */\n  public remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>> {\n    this._vectors.delete(edgeTargetKey(target));\n    return Promise.resolve(succeed(target));\n  }\n\n  /** {@inheritDoc IVectorIndex.query} */\n  public query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>> {\n    if (topK <= 0 || this._vectors.size === 0) {\n      return Promise.resolve(succeed([]));\n    }\n    if (vector.length !== this._dimension) {\n      return Promise.resolve(\n        fail(\n          `vector index: query dimension ${vector.length} does not match index dimension ${this._dimension}`\n        )\n      );\n    }\n    const queryMagnitude: number = InMemoryCosineIndex._magnitude(vector);\n    const hits: IVectorQueryHit[] = [];\n    for (const stored of this._vectors.values()) {\n      hits.push({\n        target: stored.target,\n        score: InMemoryCosineIndex._cosine(vector, queryMagnitude, stored.vector)\n      });\n    }\n    // Descending by score; a `seq`-free tiebreak is unnecessary here because the\n    // caller (SemanticRetriever) re-resolves hits against the record index.\n    hits.sort((a, b) => b.score - a.score);\n    return Promise.resolve(succeed(hits.length > topK ? hits.slice(0, topK) : hits));\n  }\n\n  /**\n   * Re-embed every record from `source` and rebuild the index from scratch.\n   * Clears the current contents (and the established dimension) first, so a\n   * re-embed with a different model is supported. Returns an\n   * {@link IVectorRebuildReport} describing what was indexed, declined and skipped.\n   *\n   * @remarks\n   * **A failure to LIST is always fatal**, under either mode — and **leaves the\n   * existing index untouched**: an unreadable source says nothing about which\n   * records exist, so there is neither an honest partial to report nor any reason\n   * to discard what is already held.\n   *\n   * Per-record embed/add failures are governed by\n   * {@link IVectorRebuildOptions.onRecordError}, which defaults to `'fail'` —\n   * **the historical all-or-nothing contract, unchanged**: the index is rolled back\n   * to empty rather than left partially rebuilt, so a caller that retries a query\n   * sees a clean empty index it can reason about.\n   *\n   * `'skip'` opts into the lenient shape the store's own open already uses: the\n   * rebuild continues and every casualty is returned structurally on\n   * {@link IVectorRebuildReport.skipped}. **It reports more, it does not report\n   * less** — the point is to stop one bad record emptying an entire index, not to\n   * make failures quieter. A caller that ignores `skipped` under `'skip'` has\n   * chosen to, rather than been given no way to know.\n   *\n   * A {@link MemoryEmbedder} decline is not a failure under either mode: it is\n   * counted on {@link IVectorRebuildReport.declined} and never appears in `skipped`.\n   *\n   * Both consumer-supplied hooks are capture-wrapped, so a `source` or `embed`\n   * that throws or rejects becomes a `Failure` on the path above rather than an\n   * exception escaping mid-rebuild — which would bypass the rollback entirely.\n   *\n   * @param source - The scope-qualified record source to re-embed.\n   * @param embed - The embedder applied to each record.\n   * @param options - Rebuild options; omit for the historical `'fail'` behavior.\n   */\n  public async rebuild(\n    source: IMemoryRecordSource,\n    embed: MemoryEmbedder,\n    options?: IVectorRebuildOptions\n  ): Promise<Result<IVectorRebuildReport>> {\n    const lenient: boolean = (options?.onRecordError ?? 'fail') === 'skip';\n    const listed: Result<ReadonlyArray<IScopedMemoryRecord>> = await invokeHook(() => source.list());\n    if (listed.isFailure()) {\n      // Deliberately BEFORE the reset. This used to reset first, on the reasoning\n      // that no stale vectors should survive a failed rebuild — but a failed list\n      // is no evidence about the vectors already held, and nothing has been\n      // re-embedded yet, so there is no half-rebuilt state to guard against.\n      // Leaving the prior contents intact is the more correct answer, and on the\n      // durable sibling (`SqliteVecVectorIndex`) resetting here was data loss.\n      return fail(`vector index rebuild: failed to list records: ${listed.message}`);\n    }\n    // From here a rebuild is genuinely starting, so clear. A mid-loop failure\n    // under `'fail'` still resets, which is what keeps that contract honest.\n    this._reset();\n    let declined: number = 0;\n    const skipped: ISkippedVectorRecord[] = [];\n    for (const scoped of listed.value) {\n      // Both hooks are consumer-supplied, so a throw or rejection is captured\n      // into a `Failure` rather than escaping as an exception — otherwise a\n      // badly-behaved embedder would reject out of `rebuild` mid-loop and leave\n      // the index half-populated, which is precisely what the rollback below\n      // exists to prevent.\n      const embedded: Result<Float32Array | undefined> = await invokeHook(() => embed(scoped.record));\n      if (embedded.isFailure()) {\n        const error: string = `vector index rebuild: embedding '${edgeTargetKey(scoped.target)}' failed: ${\n          embedded.message\n        }`;\n        // `'fail'` keeps the historical all-or-nothing contract EXACTLY: reset and\n        // abort, so a caller that retries a query sees a clean empty index rather\n        // than a partially-rebuilt one it cannot reason about.\n        if (!lenient) {\n          this._reset();\n          return fail(error);\n        }\n        skipped.push({ target: scoped.target, error });\n        continue;\n      }\n      // A decline is not an error under either mode — it is counted, never skipped.\n      if (embedded.value === undefined) {\n        declined++;\n        continue;\n      }\n      const added: Result<string> = await this.add(scoped.target, embedded.value);\n      if (added.isFailure()) {\n        const error: string = `vector index rebuild: ${added.message}`;\n        if (!lenient) {\n          this._reset();\n          return fail(error);\n        }\n        skipped.push({ target: scoped.target, error });\n      }\n    }\n    return succeed({ indexed: this._vectors.size, declined, skipped });\n  }\n\n  /** Empty the index and forget the established dimension. */\n  private _reset(): void {\n    this._vectors.clear();\n    this._dimension = undefined;\n  }\n\n  /** The Euclidean magnitude (L2 norm) of a vector. */\n  private static _magnitude(vector: Float32Array): number {\n    let sum: number = 0;\n    for (let i: number = 0; i < vector.length; i++) {\n      sum += vector[i] * vector[i];\n    }\n    return Math.sqrt(sum);\n  }\n\n  /**\n   * Cosine similarity between the query (whose magnitude is precomputed once and\n   * reused across the scan) and a stored vector. A zero-magnitude vector on\n   * either side yields `0` rather than `NaN` — a degenerate vector is simply\n   * maximally dissimilar, not an error.\n   */\n  private static _cosine(query: Float32Array, queryMagnitude: number, stored: Float32Array): number {\n    const storedMagnitude: number = InMemoryCosineIndex._magnitude(stored);\n    if (queryMagnitude === 0 || storedMagnitude === 0) {\n      return 0;\n    }\n    let dot: number = 0;\n    for (let i: number = 0; i < query.length; i++) {\n      dot += query[i] * stored[i];\n    }\n    return dot / (queryMagnitude * storedMagnitude);\n  }\n}\n"]}

package/dist/packlets/vector/inMemoryFragmentCosineIndex.js

@@ -152,6 +152,13 @@ export class InMemoryFragmentCosineIndex {
      * On any failure (list, embed, or add) the index is rolled back to empty rather
      * than left in a partially-rebuilt state.
      *
+     * @remarks
+     * **Deliberately still returns a bare count**, unlike the record-granular
+     * {@link InMemoryCosineIndex.rebuild}, which reports an
+     * {@link IVectorRebuildReport}. The asymmetry is scope, not oversight: the
+     * fragment path is tracked separately and gains the same treatment when the
+     * `IVectorIndex`/`IFragmentVectorIndex` contracts are revisited together.
+     *
      * @param source - The scope-qualified record source to re-embed.
      * @param embed - The fragment embedder applied to each record.
      */