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

package/lib/packlets/vector/inMemoryFragmentCosineIndex.js.map

@@ -1 +1 @@
-{"version":3,"file":"inMemoryFragmentCosineIndex.js","sourceRoot":"","sources":["../../../src/packlets/vector/inMemoryFragmentCosineIndex.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  FragmentEmbedder,\n  IEmbeddedFragment,\n  IFragmentVectorIndex,\n  IMemoryRecordSource,\n  IScopedMemoryRecord,\n  IVectorQueryHit\n} from './vectorIndex';\n\n/**\n * The identity fields a fragment was added with, already in query-hit shape: a field\n * the fragment did not carry is *absent*, never present-but-`undefined`, so a hit\n * for a fragment added without a `fragmentId` is structurally identical to one\n * produced before `fragmentId` existed.\n */\ntype FragmentIdentity = Pick<IVectorQueryHit, 'locator' | 'fragmentId'>;\n\n/** Project an incoming fragment's identity fields, dropping the ones it did not carry. */\nfunction fragmentIdentity(fragment: IEmbeddedFragment): FragmentIdentity {\n  return {\n    ...(fragment.locator !== undefined ? { locator: fragment.locator } : {}),\n    ...(fragment.fragmentId !== undefined ? { fragmentId: fragment.fragmentId } : {})\n  };\n}\n\n/** One stored fragment: the identity it was added with plus its vector. */\ninterface IStoredFragment {\n  readonly identity: FragmentIdentity;\n  readonly vector: Float32Array;\n}\n\n/** Every stored fragment for one record, tagged with the record's scoped address. */\ninterface IStoredRecordFragments {\n  readonly target: IEdgeTarget;\n  readonly fragments: IStoredFragment[];\n}\n\n/** A candidate hit carried through selection: the fragment's key, hit, and score. */\ninterface IScoredFragment {\n  readonly key: string;\n  readonly hit: IVectorQueryHit;\n}\n\n/**\n * The brute-force, in-memory cosine {@link IFragmentVectorIndex} — the\n * fragment-granular sibling of {@link InMemoryCosineIndex}. Stores many\n * `Float32Array`s per record (one per {@link IEmbeddedFragment | fragment}) and\n * answers a query by computing cosine similarity against every stored fragment,\n * returning the top-k fragment hits by descending score. Each hit carries back\n * whichever of {@link IFragmentLocator | locator} / `fragmentId` its fragment was\n * added with; a fragment must carry at least one of the two.\n *\n * @remarks\n * Same regime and same non-goals as {@link InMemoryCosineIndex}: no external\n * dependency, no ANN structure, a linear scan over the stored fragments — the seam\n * ({@link IFragmentVectorIndex}) stays open for a consumer to swap a persistent /\n * ANN backend once N grows. `addFragments` is whole-record-replace, so re-authoring\n * a document never leaves stale fragments behind. The index has a single dimension\n * established by the first fragment added; every subsequent fragment and every\n * `query` vector must match it or fail loudly — a mismatched dimension is an\n * embedder-wiring bug, never a silent zero-similarity result.\n * {@link InMemoryFragmentCosineIndex.rebuild | rebuild} clears the index (and the\n * established dimension), so a re-embed with a different model is supported.\n *\n * The optional `maxPerRecord` cap on `query` is applied **during selection**, before\n * the `topK` cut, so one long document with many strong fragments cannot crowd every\n * other record out of the result.\n * @public\n */\nexport class InMemoryFragmentCosineIndex implements IFragmentVectorIndex {\n  /**\n   * Stored fragments keyed by the canonical {@link edgeTargetKey} of the record's\n   * scope-qualified address, so two records that share a filename stem across\n   * scopes occupy distinct entries and never overwrite each other's fragments.\n   */\n  private readonly _records: Map<string, IStoredRecordFragments>;\n  /** The dimension of every stored fragment vector; `undefined` until the first `add`. */\n  private _dimension: number | undefined;\n\n  private constructor() {\n    this._records = new Map<string, IStoredRecordFragments>();\n    this._dimension = undefined;\n  }\n\n  /** The number of records that currently have at least one stored fragment. */\n  public get recordCount(): number {\n    return this._records.size;\n  }\n\n  /** The total number of fragments currently held across all records. */\n  public get fragmentCount(): number {\n    let total: number = 0;\n    for (const record of this._records.values()) {\n      total += record.fragments.length;\n    }\n    return total;\n  }\n\n  /** Family-convention factory. */\n  public static create(): Result<InMemoryFragmentCosineIndex> {\n    return succeed(new InMemoryFragmentCosineIndex());\n  }\n\n  /** {@inheritDoc IFragmentVectorIndex.addFragments} */\n  public addFragments(\n    target: IEdgeTarget,\n    fragments: ReadonlyArray<IEmbeddedFragment>\n  ): Promise<Result<number>> {\n    const key: string = edgeTargetKey(target);\n    // Validate every fragment before mutating any state, so a bad fragment never\n    // leaves the record half-replaced OR the index dimension half-established\n    // (whole-record-replace must be all-or-nothing). The effective dimension is the\n    // established one, or — on a still-dimensionless index — the first fragment's\n    // length; it is only committed to `this._dimension` once the whole batch passes.\n    const stored: IStoredFragment[] = [];\n    let dimension: number | undefined = this._dimension;\n    for (const fragment of fragments) {\n      if (fragment.vector.length === 0) {\n        return Promise.resolve(fail(`fragment index: cannot add '${key}': empty fragment vector`));\n      }\n      // A fragment carrying neither identity cannot be resolved back to anything by a\n      // consumer holding the hit — the same invariant `embeddedFragmentConverter`\n      // enforces at the untyped boundary, re-checked here at the index seam.\n      if (fragment.locator === undefined && fragment.fragmentId === undefined) {\n        return Promise.resolve(\n          fail(\n            `fragment index: cannot add '${key}': fragment requires at least one of 'locator' or 'fragmentId'`\n          )\n        );\n      }\n      if (dimension === undefined) {\n        dimension = fragment.vector.length;\n      } else if (fragment.vector.length !== dimension) {\n        return Promise.resolve(\n          fail(\n            `fragment index: cannot add '${key}': fragment dimension ${fragment.vector.length} does not match index dimension ${dimension}`\n          )\n        );\n      }\n      // Defensive copy: the caller may reuse or mutate the buffer after `addFragments`.\n      stored.push({ identity: fragmentIdentity(fragment), vector: Float32Array.from(fragment.vector) });\n    }\n    // Whole-record replace: an empty `fragments` array drops the record entirely\n    // rather than leaving an empty shell behind. Commit the (possibly newly-derived)\n    // dimension only alongside a successful, non-empty store.\n    if (stored.length === 0) {\n      this._records.delete(key);\n    } else {\n      this._dimension = dimension;\n      this._records.set(key, { target, fragments: stored });\n    }\n    return Promise.resolve(succeed(stored.length));\n  }\n\n  /** {@inheritDoc IFragmentVectorIndex.remove} */\n  public remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>> {\n    this._records.delete(edgeTargetKey(target));\n    return Promise.resolve(succeed(target));\n  }\n\n  /** {@inheritDoc IFragmentVectorIndex.query} */\n  public query(\n    vector: Float32Array,\n    topK: number,\n    maxPerRecord?: number\n  ): Promise<Result<ReadonlyArray<IVectorQueryHit>>> {\n    if (topK <= 0 || this._records.size === 0) {\n      return Promise.resolve(succeed([]));\n    }\n    if (vector.length !== this._dimension) {\n      return Promise.resolve(\n        fail(\n          `fragment index: query dimension ${vector.length} does not match index dimension ${this._dimension}`\n        )\n      );\n    }\n    const queryMagnitude: number = InMemoryFragmentCosineIndex._magnitude(vector);\n    const scored: IScoredFragment[] = [];\n    for (const record of this._records.values()) {\n      for (const fragment of record.fragments) {\n        scored.push({\n          key: edgeTargetKey(record.target),\n          hit: {\n            target: record.target,\n            score: InMemoryFragmentCosineIndex._cosine(vector, queryMagnitude, fragment.vector),\n            ...fragment.identity\n          }\n        });\n      }\n    }\n    // Descending by score; the caller re-resolves each `(target, locator)` hit.\n    scored.sort((a, b) => b.hit.score - a.hit.score);\n\n    const hits: IVectorQueryHit[] = [];\n    // Apply the per-record cap during selection (before the topK cut) so a single\n    // long document cannot monopolize the result. `undefined` maxPerRecord means\n    // uncapped; the counter map is always allocated (tiny) so the guard narrows\n    // `maxPerRecord` directly without a non-null assertion.\n    const perRecord: Map<string, number> = new Map<string, number>();\n    for (const candidate of scored) {\n      if (hits.length >= topK) {\n        break;\n      }\n      if (maxPerRecord !== undefined) {\n        const used: number = perRecord.get(candidate.key) ?? 0;\n        if (used >= maxPerRecord) {\n          continue;\n        }\n        perRecord.set(candidate.key, used + 1);\n      }\n      hits.push(candidate.hit);\n    }\n    return Promise.resolve(succeed(hits));\n  }\n\n  /**\n   * Re-embed every record from `source` and rebuild the fragment index from\n   * scratch. Clears the current contents (and the established dimension) first, so\n   * a re-embed with a different model is supported. Returns the total number of\n   * fragments indexed.\n   *\n   * On any failure (list, embed, or add) the index is rolled back to empty rather\n   * than left in a partially-rebuilt state.\n   *\n   * @remarks\n   * **Deliberately still returns a bare count**, unlike the record-granular\n   * {@link InMemoryCosineIndex.rebuild}, which reports an\n   * {@link IVectorRebuildReport}. The asymmetry is scope, not oversight: the\n   * fragment path is tracked separately and gains the same treatment when the\n   * `IVectorIndex`/`IFragmentVectorIndex` contracts are revisited together.\n   *\n   * @param source - The scope-qualified record source to re-embed.\n   * @param embed - The fragment embedder applied to each record.\n   */\n  public async rebuild(source: IMemoryRecordSource, embed: FragmentEmbedder): Promise<Result<number>> {\n    this._reset();\n    const listed: Result<ReadonlyArray<IScopedMemoryRecord>> = await source.list();\n    if (listed.isFailure()) {\n      return fail(`fragment index rebuild: failed to list records: ${listed.message}`);\n    }\n    for (const scoped of listed.value) {\n      const embedded: Result<ReadonlyArray<IEmbeddedFragment>> = await embed(scoped.record);\n      if (embedded.isFailure()) {\n        this._reset();\n        return fail(\n          `fragment index rebuild: embedding '${edgeTargetKey(scoped.target)}' failed: ${embedded.message}`\n        );\n      }\n      const added: Result<number> = await this.addFragments(scoped.target, embedded.value);\n      if (added.isFailure()) {\n        this._reset();\n        return fail(`fragment index rebuild: ${added.message}`);\n      }\n    }\n    return succeed(this.fragmentCount);\n  }\n\n  /** Empty the index and forget the established dimension. */\n  private _reset(): void {\n    this._records.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 fragment vector. A zero-magnitude vector\n   * on either side yields `0` rather than `NaN`.\n   */\n  private static _cosine(query: Float32Array, queryMagnitude: number, stored: Float32Array): number {\n    const storedMagnitude: number = InMemoryFragmentCosineIndex._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":"inMemoryFragmentCosineIndex.js","sourceRoot":"","sources":["../../../src/packlets/vector/inMemoryFragmentCosineIndex.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { DetailedResult, Result, fail, failWithDetail, succeed, succeedWithDetail } from '@fgv/ts-utils';\nimport { IEdgeTarget, Kind, MemoryId, MemoryScopeKey, edgeTargetKey } from '../types';\nimport {\n  FragmentEmbedder,\n  IEmbeddedFragment,\n  IFragmentQueryOptions,\n  IFragmentVectorIndex,\n  IFragmentVectorRebuildReport,\n  IMemoryRecordListing,\n  IMemoryRecordSource,\n  ISkippedVectorRecord,\n  IVectorQueryHit,\n  IVectorRebuildOptions\n} from './vectorIndex';\nimport { invokeHook, tally } from './rebuildHelpers';\n\n/**\n * The identity fields a fragment was added with, already in query-hit shape: a field\n * the fragment did not carry is *absent*, never present-but-`undefined`, so a hit\n * for a fragment added without a `fragmentId` is structurally identical to one\n * produced before `fragmentId` existed.\n */\ntype FragmentIdentity = Pick<IVectorQueryHit, 'locator' | 'fragmentId'>;\n\n/** Project an incoming fragment's identity fields, dropping the ones it did not carry. */\nfunction fragmentIdentity(fragment: IEmbeddedFragment): FragmentIdentity {\n  return {\n    ...(fragment.locator !== undefined ? { locator: fragment.locator } : {}),\n    ...(fragment.fragmentId !== undefined ? { fragmentId: fragment.fragmentId } : {})\n  };\n}\n\n/** One stored fragment: the identity it was added with plus its vector. */\ninterface IStoredFragment {\n  readonly identity: FragmentIdentity;\n  readonly vector: Float32Array;\n}\n\n/** Every stored fragment for one record, tagged with the record's scoped address. */\ninterface IStoredRecordFragments {\n  readonly target: IEdgeTarget;\n  readonly fragments: IStoredFragment[];\n}\n\n/** A candidate hit carried through selection: the fragment's key, hit, and score. */\ninterface IScoredFragment {\n  readonly key: string;\n  readonly hit: IVectorQueryHit;\n}\n\n/**\n * The brute-force, in-memory cosine {@link IFragmentVectorIndex} — the\n * fragment-granular sibling of {@link InMemoryCosineIndex}. Stores many\n * `Float32Array`s per record (one per {@link IEmbeddedFragment | fragment}) and\n * answers a query by computing cosine similarity against every stored fragment,\n * returning the top-k fragment hits by descending score. Each hit carries back\n * whichever of {@link IFragmentLocator | locator} / `fragmentId` its fragment was\n * added with; a fragment must carry at least one of the two.\n *\n * @remarks\n * Same regime and same non-goals as {@link InMemoryCosineIndex}: no external\n * dependency, no ANN structure, a linear scan over the stored fragments — the seam\n * ({@link IFragmentVectorIndex}) stays open for a consumer to swap a persistent /\n * ANN backend once N grows. `addFragments` is whole-record-replace, so re-authoring\n * a document never leaves stale fragments behind. The index has a single dimension\n * established by the first fragment added; every subsequent fragment and every\n * `query` vector must match it or fail loudly — a mismatched dimension is an\n * embedder-wiring bug, never a silent zero-similarity result.\n * {@link InMemoryFragmentCosineIndex.rebuild | rebuild} clears the index (and the\n * established dimension), so a re-embed with a different model is supported.\n *\n * The optional `maxPerRecord` cap on `query` is applied **during selection**, before\n * the `topK` cut, so one long document with many strong fragments cannot crowd every\n * other record out of the result.\n * @public\n */\nexport class InMemoryFragmentCosineIndex implements IFragmentVectorIndex {\n  /**\n   * Stored fragments keyed by the canonical {@link edgeTargetKey} of the record's\n   * scope-qualified address, so two records that share a filename stem across\n   * scopes occupy distinct entries and never overwrite each other's fragments.\n   */\n  private readonly _records: Map<string, IStoredRecordFragments>;\n  /** The dimension of every stored fragment vector; `undefined` until the first `add`. */\n  private _dimension: number | undefined;\n\n  private constructor() {\n    this._records = new Map<string, IStoredRecordFragments>();\n    this._dimension = undefined;\n  }\n\n  /** The number of records that currently have at least one stored fragment. */\n  public get recordCount(): number {\n    return this._records.size;\n  }\n\n  /** The total number of fragments currently held across all records. */\n  public get fragmentCount(): number {\n    let total: number = 0;\n    for (const record of this._records.values()) {\n      total += record.fragments.length;\n    }\n    return total;\n  }\n\n  /** Family-convention factory. */\n  public static create(): Result<InMemoryFragmentCosineIndex> {\n    return succeed(new InMemoryFragmentCosineIndex());\n  }\n\n  /** {@inheritDoc IFragmentVectorIndex.addFragments} */\n  public addFragments(\n    target: IEdgeTarget,\n    fragments: ReadonlyArray<IEmbeddedFragment>\n  ): Promise<Result<number>> {\n    const key: string = edgeTargetKey(target);\n    // Validate every fragment before mutating any state, so a bad fragment never\n    // leaves the record half-replaced OR the index dimension half-established\n    // (whole-record-replace must be all-or-nothing). The effective dimension is the\n    // established one, or — on a still-dimensionless index — the first fragment's\n    // length; it is only committed to `this._dimension` once the whole batch passes.\n    const stored: IStoredFragment[] = [];\n    let dimension: number | undefined = this._dimension;\n    for (const fragment of fragments) {\n      if (fragment.vector.length === 0) {\n        return Promise.resolve(fail(`fragment index: cannot add '${key}': empty fragment vector`));\n      }\n      // A fragment carrying neither identity cannot be resolved back to anything by a\n      // consumer holding the hit — the same invariant `embeddedFragmentConverter`\n      // enforces at the untyped boundary, re-checked here at the index seam.\n      if (fragment.locator === undefined && fragment.fragmentId === undefined) {\n        return Promise.resolve(\n          fail(\n            `fragment index: cannot add '${key}': fragment requires at least one of 'locator' or 'fragmentId'`\n          )\n        );\n      }\n      if (dimension === undefined) {\n        dimension = fragment.vector.length;\n      } else if (fragment.vector.length !== dimension) {\n        return Promise.resolve(\n          fail(\n            `fragment index: cannot add '${key}': fragment dimension ${fragment.vector.length} does not match index dimension ${dimension}`\n          )\n        );\n      }\n      // Defensive copy: the caller may reuse or mutate the buffer after `addFragments`.\n      stored.push({ identity: fragmentIdentity(fragment), vector: Float32Array.from(fragment.vector) });\n    }\n    // Whole-record replace: an empty `fragments` array drops the record entirely\n    // rather than leaving an empty shell behind. Commit the (possibly newly-derived)\n    // dimension only alongside a successful, non-empty store.\n    if (stored.length === 0) {\n      this._records.delete(key);\n    } else {\n      this._dimension = dimension;\n      this._records.set(key, { target, fragments: stored });\n    }\n    return Promise.resolve(succeed(stored.length));\n  }\n\n  /** {@inheritDoc IFragmentVectorIndex.has} */\n  public has(target: IEdgeTarget): Promise<Result<boolean>> {\n    return Promise.resolve(succeed(this._records.has(edgeTargetKey(target))));\n  }\n\n  /** {@inheritDoc IFragmentVectorIndex.remove} */\n  public remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>> {\n    this._records.delete(edgeTargetKey(target));\n    return Promise.resolve(succeed(target));\n  }\n\n  /** {@inheritDoc IFragmentVectorIndex.query} */\n  public query(\n    vector: Float32Array,\n    topK: number,\n    options?: IFragmentQueryOptions\n  ): Promise<Result<ReadonlyArray<IVectorQueryHit>>> {\n    const maxPerRecord: number | undefined = options?.maxPerRecord;\n    if (topK <= 0 || this._records.size === 0) {\n      return Promise.resolve(succeed([]));\n    }\n    if (vector.length !== this._dimension) {\n      return Promise.resolve(\n        fail(\n          `fragment index: query dimension ${vector.length} does not match index dimension ${this._dimension}`\n        )\n      );\n    }\n    const queryMagnitude: number = InMemoryFragmentCosineIndex._magnitude(vector);\n    const scored: IScoredFragment[] = [];\n    // The narrowing is applied HERE — choosing which records are scored at all —\n    // rather than by filtering hits afterwards. That is the whole point: a\n    // post-filter would leave `topK` applied to the global set, so a scoped search\n    // would silently return fewer than `topK` whenever other records outscored the\n    // target's fragments.\n    for (const record of this._selectRecords(options)) {\n      for (const fragment of record.fragments) {\n        scored.push({\n          key: edgeTargetKey(record.target),\n          hit: {\n            target: record.target,\n            score: InMemoryFragmentCosineIndex._cosine(vector, queryMagnitude, fragment.vector),\n            ...fragment.identity\n          }\n        });\n      }\n    }\n    // Descending by score; the caller re-resolves each `(target, locator)` hit.\n    scored.sort((a, b) => b.hit.score - a.hit.score);\n\n    const hits: IVectorQueryHit[] = [];\n    // Apply the per-record cap during selection (before the topK cut) so a single\n    // long document cannot monopolize the result. `undefined` maxPerRecord means\n    // uncapped; the counter map is always allocated (tiny) so the guard narrows\n    // `maxPerRecord` directly without a non-null assertion.\n    const perRecord: Map<string, number> = new Map<string, number>();\n    for (const candidate of scored) {\n      if (hits.length >= topK) {\n        break;\n      }\n      if (maxPerRecord !== undefined) {\n        const used: number = perRecord.get(candidate.key) ?? 0;\n        if (used >= maxPerRecord) {\n          continue;\n        }\n        perRecord.set(candidate.key, used + 1);\n      }\n      hits.push(candidate.hit);\n    }\n    return Promise.resolve(succeed(hits));\n  }\n\n  /**\n   * The records a query is allowed to score, honoring the `scope` / `id` narrowing.\n   *\n   * @remarks\n   * The single-record case is an O(1) map lookup rather than a scan, because the\n   * record map is keyed by `edgeTargetKey`. The scope-only case (a versioned kind's\n   * per-entity subtree) is a filtered walk — still bounded by the vault, but it\n   * scores only the entity's own fragments, which is what makes the caller's `topK`\n   * meaningful.\n   */\n  private *_selectRecords(options: IFragmentQueryOptions | undefined): Generator<IStoredRecordFragments> {\n    // Narrowed once, deliberately: re-deriving through `options?.` a second time\n    // after an early return that already implies `options !== undefined` creates an\n    // optional-chain arm that cannot fire, which is a dead branch rather than an\n    // untested one.\n    if (options === undefined || options.scope === undefined) {\n      yield* this._records.values();\n      return;\n    }\n    const scope: MemoryScopeKey = options.scope;\n    const id: MemoryId | undefined = options.id;\n    if (id !== undefined) {\n      const record: IStoredRecordFragments | undefined = this._records.get(edgeTargetKey({ scope, id }));\n      if (record !== undefined) {\n        yield record;\n      }\n      return;\n    }\n    for (const record of this._records.values()) {\n      if (record.target.scope === scope) {\n        yield record;\n      }\n    }\n  }\n\n  /**\n   * Re-embed every record from `source` and rebuild the fragment index from\n   * scratch. Clears the current contents (and the established dimension) first, so\n   * a re-embed with a different model is supported. Returns the total number of\n   * fragments indexed.\n   *\n   * On any failure (list, embed, or add) the index is rolled back to empty rather\n   * than left in a partially-rebuilt state.\n   *\n   * @remarks\n   * **Deliberately still returns a bare count**, unlike the record-granular\n   * {@link InMemoryCosineIndex.rebuild}, which reports an\n   * {@link IVectorRebuildReport}. The asymmetry is scope, not oversight: the\n   * fragment path is tracked separately and gains the same treatment when the\n   * `IVectorIndex`/`IFragmentVectorIndex` contracts are revisited together.\n   *\n   * @param source - The scope-qualified record source to re-embed.\n   * @param embed - The fragment embedder applied to each record.\n   */\n  /** {@inheritDoc IFragmentVectorIndex.rebuild} */\n  public async rebuild(\n    source: IMemoryRecordSource,\n    embed: FragmentEmbedder,\n    options?: IVectorRebuildOptions\n  ): Promise<DetailedResult<IFragmentVectorRebuildReport, IFragmentVectorRebuildReport>> {\n    const lenient: boolean = (options?.onRecordError ?? 'fail') === 'skip';\n    const listed: Result<IMemoryRecordListing> = await invokeHook(() => source.list());\n    if (listed.isFailure()) {\n      // Deliberately BEFORE the reset, matching the record-granular sibling: a\n      // failed list is no evidence about the fragments already held, and nothing\n      // has been re-embedded yet, so there is no half-rebuilt state to guard\n      // against. Discarding a healthy index over a transient read error is data\n      // loss, not caution. No detail either — an all-zero report would describe\n      // an index this call never touched.\n      return failWithDetail(`fragment 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    const indexed: Map<Kind, number> = new Map<Kind, number>();\n    const fragments: Map<Kind, number> = new Map<Kind, number>();\n    const declined: Map<Kind, number> = new Map<Kind, number>();\n    const skipped: ISkippedVectorRecord[] = [];\n    // Only the source knows what it filtered, so an absent `excluded` propagates\n    // as absent rather than becoming an empty map. Before this contract existed\n    // the fragment path dropped this tally on the floor, having nowhere honest to\n    // put it.\n    const report = (): IFragmentVectorRebuildReport => ({\n      indexed,\n      fragments,\n      declined,\n      excluded: listed.value.excluded,\n      skipped\n    });\n    for (const scoped of listed.value.records) {\n      const kind: Kind = scoped.record.envelope.kind;\n      // Consumer-supplied, so a throw or rejection is captured rather than\n      // escaping mid-loop and leaving the index half-populated.\n      const embedded: Result<ReadonlyArray<IEmbeddedFragment>> = await invokeHook(() => embed(scoped.record));\n      if (embedded.isFailure()) {\n        const error: string = `fragment index rebuild: embedding '${edgeTargetKey(scoped.target)}' failed: ${\n          embedded.message\n        }`;\n        if (!lenient) {\n          this._reset();\n          return failWithDetail(error, report());\n        }\n        skipped.push({ target: scoped.target, error });\n        continue;\n      }\n      // An empty array is this lane's decline. It still performs a real\n      // whole-record-replace — which is what clears any stale fragments — so it\n      // is written, then counted as declined rather than indexed.\n      const added: Result<number> = await this.addFragments(scoped.target, embedded.value);\n      if (added.isFailure()) {\n        const error: string = `fragment index rebuild: ${added.message}`;\n        if (!lenient) {\n          this._reset();\n          return failWithDetail(error, report());\n        }\n        skipped.push({ target: scoped.target, error });\n        continue;\n      }\n      if (added.value === 0) {\n        tally(declined, kind);\n        continue;\n      }\n      // Tallied per successful add rather than read back off the counts at the\n      // end, so the per-kind buckets line up with their siblings.\n      tally(indexed, kind);\n      tally(fragments, kind, added.value);\n    }\n    return succeedWithDetail(report());\n  }\n\n  /** Empty the index and forget the established dimension. */\n  private _reset(): void {\n    this._records.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 fragment vector. A zero-magnitude vector\n   * on either side yields `0` rather than `NaN`.\n   */\n  private static _cosine(query: Float32Array, queryMagnitude: number, stored: Float32Array): number {\n    const storedMagnitude: number = InMemoryFragmentCosineIndex._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/lib/packlets/vector/rebuildHelpers.d.ts

@@ -0,0 +1,30 @@
+import { Result } from '@fgv/ts-utils';
+import { Kind } 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.
+ *
+ * @remarks
+ * Package-internal, and deliberately not exported from the package surface: both
+ * shipped index implementations need it, which is what moved it out of
+ * `inMemoryCosineIndex.ts`, but publishing it would invite treating the
+ * invocation shape as part of the `IVectorIndex` contract when only the report
+ * is.
+ */
+export declare function invokeHook<T>(hook: () => Promise<Result<T>>): Promise<Result<T>>;
+/**
+ * Increment `kind`'s tally by `by` (default one).
+ *
+ * @remarks
+ * Package-internal for the same reason as {@link invokeHook}: publishing a
+ * mutation primitive would buy nothing a caller could not write, and would invite
+ * treating the accumulation shape as contractual.
+ *
+ * The `by` parameter exists for the fragment lane, whose `fragments` count
+ * accumulates a fan-out rather than a record count — the one place a rebuild adds
+ * more than one per record.
+ */
+export declare function tally(counts: Map<Kind, number>, kind: Kind, by?: number): void;
+//# sourceMappingURL=rebuildHelpers.d.ts.map

package/lib/packlets/vector/rebuildHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rebuildHelpers.d.ts","sourceRoot":"","sources":["../../../src/packlets/vector/rebuildHelpers.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAsB,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhC;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAEtF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,GAAE,MAAU,GAAG,IAAI,CAEjF"}

package/lib/packlets/vector/rebuildHelpers.js

@@ -0,0 +1,42 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.invokeHook = invokeHook;
+exports.tally = tally;
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * 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.
+ *
+ * @remarks
+ * Package-internal, and deliberately not exported from the package surface: both
+ * shipped index implementations need it, which is what moved it out of
+ * `inMemoryCosineIndex.ts`, but publishing it would invite treating the
+ * invocation shape as part of the `IVectorIndex` contract when only the report
+ * is.
+ */
+async function invokeHook(hook) {
+    return (await (0, ts_utils_1.captureAsyncResult)(hook)).onSuccess((inner) => inner);
+}
+/**
+ * Increment `kind`'s tally by `by` (default one).
+ *
+ * @remarks
+ * Package-internal for the same reason as {@link invokeHook}: publishing a
+ * mutation primitive would buy nothing a caller could not write, and would invite
+ * treating the accumulation shape as contractual.
+ *
+ * The `by` parameter exists for the fragment lane, whose `fragments` count
+ * accumulates a fan-out rather than a record count — the one place a rebuild adds
+ * more than one per record.
+ */
+function tally(counts, kind, by = 1) {
+    var _a;
+    counts.set(kind, ((_a = counts.get(kind)) !== null && _a !== void 0 ? _a : 0) + by);
+}
+//# sourceMappingURL=rebuildHelpers.js.map

package/lib/packlets/vector/rebuildHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rebuildHelpers.js","sourceRoot":"","sources":["../../../src/packlets/vector/rebuildHelpers.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAkBH,gCAEC;AAcD,sBAEC;AAlCD,4CAA2D;AAG3D;;;;;;;;;;;;GAYG;AACI,KAAK,UAAU,UAAU,CAAI,IAA8B;IAChE,OAAO,CAAC,MAAM,IAAA,6BAAkB,EAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,KAAK,CAAC,MAAyB,EAAE,IAAU,EAAE,KAAa,CAAC;;IACzE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAA,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,mCAAI,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;AACjD,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, captureAsyncResult } from '@fgv/ts-utils';\nimport { Kind } from '../types';\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 *\n * @remarks\n * Package-internal, and deliberately not exported from the package surface: both\n * shipped index implementations need it, which is what moved it out of\n * `inMemoryCosineIndex.ts`, but publishing it would invite treating the\n * invocation shape as part of the `IVectorIndex` contract when only the report\n * is.\n */\nexport async function invokeHook<T>(hook: () => Promise<Result<T>>): Promise<Result<T>> {\n  return (await captureAsyncResult(hook)).onSuccess((inner) => inner);\n}\n\n/**\n * Increment `kind`'s tally by `by` (default one).\n *\n * @remarks\n * Package-internal for the same reason as {@link invokeHook}: publishing a\n * mutation primitive would buy nothing a caller could not write, and would invite\n * treating the accumulation shape as contractual.\n *\n * The `by` parameter exists for the fragment lane, whose `fragments` count\n * accumulates a fan-out rather than a record count — the one place a rebuild adds\n * more than one per record.\n */\nexport function tally(counts: Map<Kind, number>, kind: Kind, by: number = 1): void {\n  counts.set(kind, (counts.get(kind) ?? 0) + by);\n}\n"]}

package/lib/packlets/vector/vectorIndex.d.ts

@@ -1,5 +1,5 @@
-import { Result } from '@fgv/ts-utils';
-import { IEdgeTarget, IMemoryRecord } from '../types';
+import { DetailedResult, Result } from '@fgv/ts-utils';
+import { IEdgeTarget, IMemoryRecord, Kind, MemoryId, MemoryScopeKey } from '../types';
 /**
  * A half-open `[start, end)` span into a record's body — the in-record locator a
  * {@link IFragmentVectorIndex} may carry on a fragment. `start` is inclusive,
@@ -117,6 +117,32 @@ export interface IVectorIndex {
      * Return the `topK` nearest records to `vector`, in descending score order.
      */
     query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    /**
+     * Whether this index holds a vector for the scope-qualified `target`.
+     *
+     * @remarks
+     * On the contract because it is what makes a **targeted** repair possible, and
+     * the reason is sharper than convenience: the only other way to ask *"is this
+     * record indexed?"* is {@link IMemoryEnvelope.embeddingRef} — and that field is
+     * the store's **belief**, which is wrong in precisely the situation a repair
+     * runs in. A reopened vault backed by a fresh in-memory index carries an
+     * `embeddingRef` on every record while holding no vectors at all. **A repair
+     * that trusts the field it is repairing is not a repair.**
+     *
+     * It also makes a case *detectable* that an `embeddingRef`-only check cannot
+     * see at all: the index holds the vector but the envelope lost its reference
+     * (a failure swallowed after the vector was committed). That record needs its
+     * reference restamped and **no embedder call**, which is only knowable by
+     * asking the index.
+     *
+     * `Promise<Result<boolean>>`, unlike the synchronous {@link IVectorIndex.size},
+     * because the two are not the same kind of accessor and should not be made to
+     * look alike: `size` is a count both shipped implementations hold or can read
+     * without a failure mode, while `has` on a durable backend is a keyed query
+     * that can fail. Idempotent and side-effect-free; an absent target is
+     * `succeed(false)`, never a failure.
+     */
+    has(target: IEdgeTarget): Promise<Result<boolean>>;
     /**
      * The number of vectors currently held.
      *
@@ -154,8 +180,36 @@ export interface IVectorIndex {
      *
      * See {@link IVectorRebuildReport} for what it reports and
      * {@link IVectorRebuildOptions} for the failure mode.
+     *
+     * **A failure carries the report too, on the `detail`** — coverage is most
+     * wanted exactly when a rebuild did not complete, and withholding it there made
+     * the answer depend on the error-handling mode rather than on the question. The
+     * `'fail'` contract itself is unchanged: it still resets, still aborts, still
+     * returns a failure. It simply also says what it had established before it
+     * stopped. See {@link IVectorRebuildReport} for how to read a report that
+     * arrived on a failure — it describes the attempt, not the surviving index.
+     *
+     * On success the report is the **value** — that is where it belongs, and the
+     * `detail` is not also populated. A failure carries no report when nothing was
+     * attempted: always a `source.list()` failure, and additionally whatever
+     * pre-loop step an implementation needs before it can start (the durable
+     * `SqliteVecVectorIndex` must clear its table, and a failure to do so is such a
+     * case). Those leave the existing index untouched, so an all-zero report would
+     * describe an index the call never disturbed.
+     *
+     * **A rebuild does NOT re-establish the vector dimension on a persistent
+     * index, and this is the one place the two shipped implementations genuinely
+     * differ.** The in-memory indexes forget their dimension when they reset, so a
+     * rebuild with a different-dimension embedder simply re-establishes it. A
+     * `vec0`-backed index cannot: its reset is a `DELETE FROM`, the table's
+     * declared dimension is part of its schema, and `vec0` has no `ALTER TABLE`.
+     * So a rebuild that changes dimension **succeeds in memory and fails on
+     * SQLite**, where it needs the same drop-and-re-index the package README
+     * prescribes for any schema change (drop the table, or point the index at a
+     * fresh `tableName`). Only embedding time is at risk — vectors are derived and
+     * the vault records remain authoritative.
      */
-    rebuild(source: IMemoryRecordSource, embed: MemoryEmbedder, options?: IVectorRebuildOptions): Promise<Result<IVectorRebuildReport>>;
+    rebuild(source: IMemoryRecordSource, embed: MemoryEmbedder, options?: IVectorRebuildOptions): Promise<DetailedResult<IVectorRebuildReport, IVectorRebuildReport>>;
 }
 /**
  * One embedded fragment of a record: the fragment's vector, plus at least one of the
@@ -198,6 +252,53 @@ export interface IEmbeddedFragment {
     /** The embedding vector for this fragment. */
     readonly vector: Float32Array;
 }
+/**
+ * Selection-time narrowing for {@link IFragmentVectorIndex.query}. Every member is
+ * applied **before** the `topK` cut.
+ *
+ * @remarks
+ * `scope` (optionally with `id`) is the record narrowing. It is expressed as a
+ * storage address rather than as a consumer-facing `(kind, entityId)` because that
+ * is what the index is keyed by; resolving one to the other is
+ * `IIdentityResolver.resolveIdentity`'s job, and doing it above the index keeps the
+ * index dealing only in the keys it actually holds.
+ *
+ * **`scope` alone is not a coarser accident — it is what a versioned kind needs.**
+ * `TemporalIdentityCodec` files every version of an entity in its own per-entity
+ * subtree, so for a versioned kind the entity's subtree *is* the narrowing and
+ * `{ scope }` means "every version of this entity". A non-versioned kind resolves to
+ * a single record and supplies `{ scope, id }`.
+ *
+ * **"Every version" is literal, and includes superseded ones.** Invalidation stamps
+ * `invalid_at` on an envelope; it does not prune that version's fragments from the
+ * index. So a scope-narrowed query returns current and historical fragments alike,
+ * and a hit carries nothing that distinguishes them — `IVectorQueryHit` has no
+ * temporal fields. This is the record-granular vector lane's existing behaviour
+ * rather than something this narrowing introduces, but do not read the subtree
+ * narrowing as currency filtering: it is not, and there is no `asOf` axis here to
+ * make it so.
+ * @public
+ */
+export interface IFragmentQueryOptions {
+    /**
+     * Maximum number of fragments any single record may contribute. Omit for
+     * uncapped. With a single-record narrowing (`scope` + `id`) this caps the one
+     * record's contribution, which is a second cap on the same axis rather than a
+     * cross-record fairness knob — usually you want one or the other, not both.
+     */
+    readonly maxPerRecord?: number;
+    /**
+     * Restrict the search to fragments of records in this scope. Omit to search every
+     * record.
+     */
+    readonly scope?: MemoryScopeKey;
+    /**
+     * With {@link IFragmentQueryOptions.scope}, restrict further to the single record
+     * at `(scope, id)`. Ignored — and meaningless — without `scope`, since a bare `id`
+     * does not address a record.
+     */
+    readonly id?: MemoryId;
+}
 /**
  * The fragment-granular sibling of {@link IVectorIndex}: instead of one vector per
  * record it holds many vectors per record, each tagged with the identity its
@@ -234,12 +335,123 @@ export interface IFragmentVectorIndex {
     /**
      * Return the `topK` nearest fragments to `vector`, in descending score order,
      * each hit carrying its record `target` plus whichever of `locator` /
-     * `fragmentId` the stored fragment was added with. When
-     * `maxPerRecord` is supplied, no more than that many fragments of any single
-     * record appear in the result — the cap is applied during selection (before the
-     * `topK` cut) so one long document cannot crowd out others.
+     * `fragmentId` the stored fragment was added with.
+     *
+     * @remarks
+     * **Every member of `options` is applied during selection, before the `topK`
+     * cut.** That ordering is the contract, not an implementation detail: a narrowing
+     * applied afterwards would mean the caller's `topK` is not the `topK` that reached
+     * the index, so a scoped search would be exact only when a global over-fetch
+     * happened to be generous enough. See {@link IFragmentQueryOptions}.
+     */
+    query(vector: Float32Array, topK: number, options?: IFragmentQueryOptions): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    /**
+     * Whether this index holds **any** fragment for the scope-qualified `target`.
+     *
+     * @remarks
+     * The record-granular rationale on {@link IVectorIndex.has} applies verbatim —
+     * a repair that trusts `embeddingRef` is not a repair. Note the granularity
+     * this deliberately does **not** offer: it answers *"is this record
+     * represented?"*, not *"is this particular fragment present?"*. Fragment
+     * writes are whole-record-replace, so a record is either represented by the
+     * current fragment set or not represented at all; a per-fragment membership
+     * check would imply an incremental write path that does not exist.
+     */
+    has(target: IEdgeTarget): Promise<Result<boolean>>;
+    /**
+     * The number of **records** with at least one fragment held.
+     *
+     * @remarks
+     * Deliberately **not** named `size`, unlike {@link IVectorIndex.size}. This
+     * index is one-to-many, so `size` has two defensible readings and a reader
+     * arriving from the record-granular sibling — where `size` counts vectors —
+     * would take the wrong one silently. Two explicitly-named counts cost one extra
+     * member and cannot be misread.
+     */
+    readonly recordCount: number;
+    /**
+     * The total number of **fragments** held across all records.
+     *
+     * @remarks
+     * The fan-out, and the number a caller actually watches: fragments-per-record
+     * is what makes a fragment reconcile expensive, and neither `recordCount` nor a
+     * record-granular count answers it.
+     */
+    readonly fragmentCount: number;
+    /**
+     * Re-embed every record from `source` and rebuild the fragment index from
+     * scratch — the **backfill / reconcile** operation, sibling to
+     * {@link IVectorIndex.rebuild}.
+     *
+     * @remarks
+     * On the contract for exactly the reasons its record-granular sibling is, and
+     * the fragment lane was worse off: `rebuild` existed only on the bundled
+     * in-memory class, and the durable `SqliteVecFragmentIndex` had **no backfill
+     * at all**, so a persistent fragment index could not be reconciled by any
+     * route — contractual or concrete. Records written while it was unwired, a
+     * re-embed after a segmenter change, and reconciliation after a swallowed
+     * fragment-embed failure were all unreachable.
+     *
+     * Semantics are kept observably identical to the record-granular sibling so a
+     * caller who has learned one has learned both: a `source.list()` failure is
+     * fatal and carries no detail (nothing was attempted, and the existing index is
+     * untouched); a genuine rebuild then resets first; `onRecordError` defaults to
+     * `'fail'`; and a failure carries whatever the attempt had established on the
+     * `detail`.
+     *
+     * **A rebuild does NOT re-establish the vector dimension on a persistent
+     * index, and this is the one place the two shipped implementations genuinely
+     * differ.** The in-memory indexes forget their dimension when they reset, so a
+     * rebuild with a different-dimension embedder simply re-establishes it. A
+     * `vec0`-backed index cannot: its reset is a `DELETE FROM`, the table's
+     * declared dimension is part of its schema, and `vec0` has no `ALTER TABLE`.
+     * So a rebuild that changes dimension **succeeds in memory and fails on
+     * SQLite**, where it needs the same drop-and-re-index the package README
+     * prescribes for any schema change (drop the table, or point the index at a
+     * fresh `tableName`). Only embedding time is at risk — vectors are derived and
+     * the vault records remain authoritative.
+     */
+    rebuild(source: IMemoryRecordSource, embed: FragmentEmbedder, options?: IVectorRebuildOptions): Promise<DetailedResult<IFragmentVectorRebuildReport, IFragmentVectorRebuildReport>>;
+}
+/**
+ * What an {@link IFragmentVectorIndex.rebuild} established, resolved by
+ * {@link Kind} — the fragment-granular sibling of {@link IVectorRebuildReport}.
+ *
+ * @remarks
+ * The rule stated on {@link IVectorRebuildReport} applies here verbatim and is
+ * not re-opened: **every count is resolved by kind unless there is a stated
+ * reason it cannot be**, `excluded` is optional because only the source can know
+ * it, and the report is carried on a failure as well as a success.
+ *
+ * The one member with no record-granular analogue is
+ * {@link IFragmentVectorRebuildReport.fragments | fragments} — the fan-out. It is
+ * the number that distinguishes this lane: `indexed: 40` says forty records are
+ * represented and says nothing about whether that cost forty embedding round
+ * trips or four thousand, which is the difference between a reconcile that
+ * finishes in a second and one that blocks a request past thirty.
+ *
+ * A **declined** record is one whose {@link FragmentEmbedder} returned an empty
+ * array — the fragment lane's way of saying *intentionally not embedded*. Note
+ * this is a different mechanism from a {@link MemoryEmbedder} decline: an empty
+ * array still performs a real whole-record-replace (which is what clears any
+ * stale fragments), where a record-granular decline skips the index entirely.
+ * @public
+ */
+export interface IFragmentVectorRebuildReport {
+    /** Records that ended with at least one fragment held, per kind. */
+    readonly indexed: ReadonlyMap<Kind, number>;
+    /** Fragments held, per kind — the fan-out `indexed` cannot express. */
+    readonly fragments: ReadonlyMap<Kind, number>;
+    /** Records whose embedder intentionally produced no fragments, per kind. */
+    readonly declined: ReadonlyMap<Kind, number>;
+    /**
+     * Records the source filtered out before the rebuild saw them, per kind.
+     * `undefined` means *this source does not report exclusions*; an empty map
+     * means *it does, and excluded nothing*.
      */
-    query(vector: Float32Array, topK: number, maxPerRecord?: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    readonly excluded?: ReadonlyMap<Kind, number>;
+    /** Records that failed, per record, with the error — a fault, never a decline. */
+    readonly skipped: ReadonlyArray<ISkippedVectorRecord>;
 }
 /**
  * How a vector-index rebuild treats a record it cannot index — whether the
@@ -277,22 +489,83 @@ export interface ISkippedVectorRecord {
  * What a rebuild actually did — the structural answer to "is this index complete?".
  *
  * @remarks
- * A bare count cannot distinguish the three ways a record can be absent from the
- * index, and that distinction is the entire point: **`declined` was intentional,
- * `skipped` was a fault, and neither is the same as "never attempted"**. A caller
- * deriving coverage from a count alone cannot tell an embedder outage from a
- * deliberate policy, which is precisely the confusion this type exists to end.
+ * A bare count cannot distinguish the ways a record can be absent from the index,
+ * and that distinction is the entire point: **`declined` was intentional,
+ * `excluded` was never offered, `skipped` was a fault, and none of them is the
+ * same as "never attempted"**. A caller deriving coverage from a count alone
+ * cannot tell an embedder outage from a deliberate policy, which is precisely the
+ * confusion this type exists to end.
+ *
+ * **Every count in this report is resolved by kind.** A coverage report exists to
+ * answer *"is my coverage what I intended?"*, and a bare total cannot:
+ * `indexed: 500` reads identically whether the right kinds were indexed or a
+ * policy drift silently redirected coverage, and the same is true of every other
+ * count here. Totals are derivable by summing; the per-kind breakdown is not
+ * derivable from anything else — {@link IVectorQueryHit} carries no `kind`,
+ * {@link IVectorIndex.query} answers "what is near this" rather than "what is in
+ * here", and {@link IVectorIndex.size} is a scalar, so the index cannot be
+ * interrogated after the fact for any of them. **A new count added to this report
+ * is resolved by kind unless there is a stated reason it cannot be.**
+ *
+ * `indexed` is the count most tempting to leave bare and the most dangerous to,
+ * because it is the number a coverage surface actually renders: 500 bookkeeping
+ * rows and zero knowledge rows is a healthy-looking number for a catastrophically
+ * broken index.
+ *
+ * **Reading a report that arrived on a failure.** Under
+ * {@link VectorRebuildErrorMode | `onRecordError: 'fail'`} the report is handed
+ * back on the failure's `detail` — *after* the rollback has already run. It
+ * describes the attempt, not the surviving index: `indexed` names what had been
+ * established when the rebuild stopped, and the index itself now holds nothing. It
+ * is a diagnostic ("we were 340 knowledge rows in when the embedder died"), not a
+ * coverage statement. Only a report from a **successful** rebuild describes what
+ * the index holds.
  * @public
  */
 export interface IVectorRebuildReport {
-    /** Records embedded and added to the index. */
-    readonly indexed: number;
-    /** Records the embedder deliberately declined (resolved `undefined`). */
-    readonly declined: number;
+    /**
+     * Records embedded and added to the index, counted by {@link Kind}.
+     *
+     * @remarks
+     * A count of successful `add` calls, so it lines up with its per-record
+     * siblings and the buckets sum back to the listing. It is deliberately **not**
+     * read back off {@link IVectorIndex.size} at the end, which no implementation
+     * could resolve by kind anyway. The trade that makes: a `source` that lists the
+     * same `(scope, id)` twice contributes twice here while the index holds one
+     * vector, where a size read would have self-corrected. A source that does that
+     * is malformed, and a total that silently disagreed with the per-kind
+     * breakdown would be the worse failure.
+     */
+    readonly indexed: ReadonlyMap<Kind, number>;
+    /**
+     * Records the embedder deliberately declined (resolved `undefined`), counted by
+     * {@link Kind}. The embedder was called and answered — contrast `excluded`,
+     * where it never was.
+     */
+    readonly declined: ReadonlyMap<Kind, number>;
+    /**
+     * Records the `source` filtered out before the rebuild ever saw them, counted by
+     * {@link Kind} — for a store-backed source, the kinds outside
+     * {@link IMemoryStore.embedsKind | embedsKind}.
+     *
+     * **Optional, and the optionality is semantic rather than cosmetic**: it is the
+     * one count a rebuild genuinely cannot know for itself, because the decision is
+     * made upstream in the source. `undefined` means *this source does not report
+     * exclusions* — distinct from an empty map, which means *this source reports
+     * them and excluded nothing*. `indexed` and `declined` are knowable by
+     * construction (the rebuild either added the vector or the embedder answered)
+     * and so are never optional.
+     */
+    readonly excluded?: ReadonlyMap<Kind, number>;
     /**
      * Records whose embedding or add FAILED and were skipped. Non-empty only under
      * {@link VectorRebuildErrorMode | `onRecordError: 'skip'`} — under `'fail'` the
-     * first failure aborts the rebuild and no report is returned at all.
+     * first failure aborts the rebuild, so a `'fail'` report names the casualty in
+     * its failure message rather than here.
+     *
+     * Per-record and carrying the error, so it already implies the per-kind
+     * breakdown the counts above spell out; that is the stated reason this one field
+     * is not a `ReadonlyMap<Kind, number>`.
      */
     readonly skipped: ReadonlyArray<ISkippedVectorRecord>;
 }
@@ -361,6 +634,35 @@ export interface IScopedMemoryRecord {
     /** The record itself, passed to the embedder. */
     readonly record: IMemoryRecord<unknown>;
 }
+/**
+ * What a {@link IMemoryRecordSource.list} call yields: the records the rebuild
+ * should embed, plus — when the source can say — what it filtered out on the way.
+ *
+ * @remarks
+ * The exclusion count originates here because **this is the layer where the
+ * decision is made**. A rebuild never sees an excluded record, so it cannot count
+ * one; a report assembled without this would silently undercount coverage, and
+ * undercount in the direction of looking healthier.
+ *
+ * A store accessor answering "how many are excluded right now" was considered and
+ * declined: it answers a *different question* than the report does — "excluded
+ * right now" versus "excluded in this reconcile" — and the two legitimately differ
+ * whenever records are written between reconciles. Two correct-and-unequal numbers
+ * are worse than one absent number: they invite treating a real difference as a
+ * bug, or picking whichever supports the conclusion already held.
+ * @public
+ */
+export interface IMemoryRecordListing {
+    /** Every record the rebuild should embed, each paired with its scoped address. */
+    readonly records: ReadonlyArray<IScopedMemoryRecord>;
+    /**
+     * Records this source filtered out, counted by {@link Kind}. Omit it entirely if
+     * the source does not track exclusions — that reads as *"cannot say"* on
+     * {@link IVectorRebuildReport.excluded}, which is distinct from an empty map
+     * (*"nothing was excluded"*).
+     */
+    readonly excluded?: ReadonlyMap<Kind, number>;
+}
 /**
  * The minimal record-source surface {@link InMemoryCosineIndex.rebuild} reads to
  * re-embed an entire vault. Each entry carries the record's scope-qualified
@@ -372,7 +674,11 @@ export interface IScopedMemoryRecord {
  * @public
  */
 export interface IMemoryRecordSource {
-    /** List every record in the vault, each paired with its scoped address. */
-    list(): Promise<Result<ReadonlyArray<IScopedMemoryRecord>>>;
+    /**
+     * List every record the rebuild should embed, each paired with its scoped
+     * address, plus the exclusions this source applied if it tracks them. See
+     * {@link IMemoryRecordListing}.
+     */
+    list(): Promise<Result<IMemoryRecordListing>>;
 }
 //# sourceMappingURL=vectorIndex.d.ts.map

package/lib/packlets/vector/vectorIndex.d.ts.map

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