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

package/dist/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   * @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":"AAAA;;;GAGG;AAEH,OAAO,EAAU,IAAI,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAe,aAAa,EAAE,MAAM,UAAU,CAAC;AAkBtD,0FAA0F;AAC1F,SAAS,gBAAgB,CAAC,QAA2B;IACnD,uCACK,CAAC,QAAQ,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,GACrE,CAAC,QAAQ,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EACjF;AACJ,CAAC;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,2BAA2B;IAUtC;QACE,IAAI,CAAC,QAAQ,GAAG,IAAI,GAAG,EAAkC,CAAC;QAC1D,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED,8EAA8E;IAC9E,IAAW,WAAW;QACpB,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC5B,CAAC;IAED,uEAAuE;IACvE,IAAW,aAAa;QACtB,IAAI,KAAK,GAAW,CAAC,CAAC;QACtB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YAC5C,KAAK,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC;QACnC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM;QAClB,OAAO,OAAO,CAAC,IAAI,2BAA2B,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,sDAAsD;IAC/C,YAAY,CACjB,MAAmB,EACnB,SAA2C;QAE3C,MAAM,GAAG,GAAW,aAAa,CAAC,MAAM,CAAC,CAAC;QAC1C,6EAA6E;QAC7E,0EAA0E;QAC1E,gFAAgF;QAChF,8EAA8E;QAC9E,iFAAiF;QACjF,MAAM,MAAM,GAAsB,EAAE,CAAC;QACrC,IAAI,SAAS,GAAuB,IAAI,CAAC,UAAU,CAAC;QACpD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACjC,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,+BAA+B,GAAG,0BAA0B,CAAC,CAAC,CAAC;YAC7F,CAAC;YACD,gFAAgF;YAChF,4EAA4E;YAC5E,uEAAuE;YACvE,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS,IAAI,QAAQ,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;gBACxE,OAAO,OAAO,CAAC,OAAO,CACpB,IAAI,CACF,+BAA+B,GAAG,gEAAgE,CACnG,CACF,CAAC;YACJ,CAAC;YACD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;YACrC,CAAC;iBAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAChD,OAAO,OAAO,CAAC,OAAO,CACpB,IAAI,CACF,+BAA+B,GAAG,yBAAyB,QAAQ,CAAC,MAAM,CAAC,MAAM,mCAAmC,SAAS,EAAE,CAChI,CACF,CAAC;YACJ,CAAC;YACD,kFAAkF;YAClF,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACpG,CAAC;QACD,6EAA6E;QAC7E,iFAAiF;QACjF,0DAA0D;QAC1D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;YAC5B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,gDAAgD;IACzC,MAAM,CAAC,MAAmB;QAC/B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;QAC5C,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1C,CAAC;IAED,+CAA+C;IACxC,KAAK,CACV,MAAoB,EACpB,IAAY,EACZ,YAAqB;;QAErB,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YAC1C,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;QACtC,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC;YACtC,OAAO,OAAO,CAAC,OAAO,CACpB,IAAI,CACF,mCAAmC,MAAM,CAAC,MAAM,mCAAmC,IAAI,CAAC,UAAU,EAAE,CACrG,CACF,CAAC;QACJ,CAAC;QACD,MAAM,cAAc,GAAW,2BAA2B,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAC9E,MAAM,MAAM,GAAsB,EAAE,CAAC;QACrC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YAC5C,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;gBACxC,MAAM,CAAC,IAAI,CAAC;oBACV,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC;oBACjC,GAAG,kBACD,MAAM,EAAE,MAAM,CAAC,MAAM,EACrB,KAAK,EAAE,2BAA2B,CAAC,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,IAChF,QAAQ,CAAC,QAAQ,CACrB;iBACF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,4EAA4E;QAC5E,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAEjD,MAAM,IAAI,GAAsB,EAAE,CAAC;QACnC,8EAA8E;QAC9E,6EAA6E;QAC7E,4EAA4E;QAC5E,wDAAwD;QACxD,MAAM,SAAS,GAAwB,IAAI,GAAG,EAAkB,CAAC;QACjE,KAAK,MAAM,SAAS,IAAI,MAAM,EAAE,CAAC;YAC/B,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;gBACxB,MAAM;YACR,CAAC;YACD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;gBAC/B,MAAM,IAAI,GAAW,MAAA,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,mCAAI,CAAC,CAAC;gBACvD,IAAI,IAAI,IAAI,YAAY,EAAE,CAAC;oBACzB,SAAS;gBACX,CAAC;gBACD,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC;YACzC,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;QACD,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACxC,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACI,KAAK,CAAC,OAAO,CAAC,MAA2B,EAAE,KAAuB;QACvE,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,MAAM,MAAM,GAA+C,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QAC/E,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC,mDAAmD,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QACnF,CAAC;QACD,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YAClC,MAAM,QAAQ,GAA6C,MAAM,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACtF,IAAI,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC;gBACzB,IAAI,CAAC,MAAM,EAAE,CAAC;gBACd,OAAO,IAAI,CACT,sCAAsC,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,aAAa,QAAQ,CAAC,OAAO,EAAE,CAClG,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,GAAmB,MAAM,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;YACrF,IAAI,KAAK,CAAC,SAAS,EAAE,EAAE,CAAC;gBACtB,IAAI,CAAC,MAAM,EAAE,CAAC;gBACd,OAAO,IAAI,CAAC,2BAA2B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YAC1D,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACrC,CAAC;IAED,4DAA4D;IACpD,MAAM;QACZ,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED,qDAAqD;IAC7C,MAAM,CAAC,UAAU,CAAC,MAAoB;QAC5C,IAAI,GAAG,GAAW,CAAC,CAAC;QACpB,KAAK,IAAI,CAAC,GAAW,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/C,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAED;;;;OAIG;IACK,MAAM,CAAC,OAAO,CAAC,KAAmB,EAAE,cAAsB,EAAE,MAAoB;QACtF,MAAM,eAAe,GAAW,2BAA2B,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAC/E,IAAI,cAAc,KAAK,CAAC,IAAI,eAAe,KAAK,CAAC,EAAE,CAAC;YAClD,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,GAAG,GAAW,CAAC,CAAC;QACpB,KAAK,IAAI,CAAC,GAAW,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC9C,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QAC9B,CAAC;QACD,OAAO,GAAG,GAAG,CAAC,cAAc,GAAG,eAAe,CAAC,CAAC;IAClD,CAAC;CACF","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"]}

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

@@ -1 +1 @@
-{"version":3,"file":"vectorIndex.js","sourceRoot":"","sources":["../../../src/packlets/vector/vectorIndex.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result } from '@fgv/ts-utils';\nimport { IEdgeTarget, IMemoryRecord } from '../types';\n\n/**\n * A half-open `[start, end)` span into a record's body — the in-record locator a\n * {@link IFragmentVectorIndex} may carry on a fragment. `start` is inclusive,\n * `end` exclusive. The unit (character / byte / token offsets) is the consumer's\n * choice: the index stores the two integers opaquely and never interprets them,\n * so they line up with whatever locator the consumer's own read side uses.\n *\n * @remarks\n * **The span is advisory.** It names the region of the body a fragment was\n * *derived from*; it is NOT a slice guaranteed to reproduce the fragment's text.\n * `body.slice(start, end)` round-trips only under a segmenter that merely chooses\n * boundaries. Under a **rewriting** segmenter — one that turns a span into a\n * curated block, an increasingly common ingestion shape when a model both selects\n * and rewrites — the fragment text is not a substring of the body at all, and the\n * fragmentation is not re-derivable from the body. Treat the span as a pointer for\n * locating context, never as an extraction recipe.\n *\n * A fragment whose provenance cannot honestly be expressed as a body span should\n * omit the locator entirely and carry an {@link IEmbeddedFragment.fragmentId}\n * instead.\n * @public\n */\nexport interface IFragmentLocator {\n  /** Inclusive start offset into the record body. */\n  readonly start: number;\n  /** Exclusive end offset into the record body. */\n  readonly end: number;\n}\n\n/**\n * A single hit returned by {@link IVectorIndex.query} (or\n * {@link IFragmentVectorIndex.query}): the matched record's scope-qualified\n * {@link IEdgeTarget | address} and the backend's similarity score (higher = more\n * similar; the exact scale is backend-defined). Hits are returned in descending\n * score order.\n *\n * @remarks\n * The address is a `(scope, id)` pair, NOT a bare {@link MemoryId} — per-scope\n * codecs (e.g. the medium-term codec's `turn-<n>` stems) legally mint the same\n * stem under different scopes, so a bare id could not disambiguate two records\n * that share a stem. The caller re-resolves the hit against the record index by\n * the same scoped address.\n *\n * **No single field discriminates a fragment hit from a record-granular hit.** A\n * record hit carries neither `locator` nor `fragmentId`; a fragment hit carries at\n * least one of the two, but not necessarily any particular one — a fragment with a\n * body span but no consumer-minted id, and a fragment with an id but no honest span,\n * are both legal. Testing one field for presence therefore cannot tell you which\n * kind of hit you hold.\n *\n * That \"at least one\" requirement is enforced on the upsert side by\n * {@link embeddedFragmentConverter} — a different boundary from this type — and is\n * deliberately NOT offered here as a discriminator either. A caller keyed off it\n * would be coupled to an invariant this type does not own, and would fail silently\n * if the invariant were ever relaxed.\n *\n * **The robust rule is that fragment-ness is determined by which index produced the\n * hit**: {@link IFragmentVectorIndex.query} returns fragment hits and\n * {@link IVectorIndex.query} returns record hits. The caller chose the index it\n * queried, so it already knows which kind it is holding.\n *\n * Note in particular that an absent `locator` now carries **two** distinct meanings\n * — a record-granular hit, or a fragment with no honest body span (see\n * {@link IFragmentLocator}) — which is precisely why presence-branching is unsafe.\n * @public\n */\nexport interface IVectorQueryHit {\n  /** The scope-qualified address of the matched record. */\n  readonly target: IEdgeTarget;\n  /** Backend similarity score; higher is more similar. */\n  readonly score: number;\n  /**\n   * The advisory in-record span the matched fragment was derived from, when the\n   * producing fragment carried one. Absent on record-granular hits AND on fragment\n   * hits with no honest span — see the remarks above; do not branch on its presence.\n   */\n  readonly locator?: IFragmentLocator;\n  /**\n   * The opaque identity the producing fragment was stored with, carried back\n   * verbatim. Absent on record-granular hits AND on fragment hits stored without\n   * one — see the remarks above; do not branch on its presence.\n   */\n  readonly fragmentId?: string;\n}\n\n/**\n * The vector-index seam an embedding backend implements to make\n * {@link SemanticRetriever | semantic recall} operational.\n *\n * @remarks\n * Vectors cross this seam as `Float32Array` (the in-memory representation an\n * embedding model produces); `number[]` is reserved for the JSON-wire edges\n * (e.g. a provider's embedding response). The in-package brute-force cosine\n * implementation is {@link InMemoryCosineIndex}; a consumer can swap an external\n * ANN backend behind the same seam once N grows beyond the in-memory regime.\n *\n * Every operation returns a `Result` (async, since a real backend does I/O) so\n * failure is explicit and never throws across the seam.\n * @public\n */\nexport interface IVectorIndex {\n  /**\n   * Add (or replace) the embedding for the scope-qualified `target`. Returns the\n   * opaque {@link IMemoryEnvelope.embeddingRef | embeddingRef} the store stamps\n   * onto the envelope so a later read knows the record is embedded. Keying on the\n   * `(scope, id)` address (not a bare id) is load-bearing: two records that share\n   * a filename stem across scopes must not clobber each other's embedding.\n   */\n  add(target: IEdgeTarget, vector: Float32Array): Promise<Result<string>>;\n\n  /**\n   * Remove the embedding for the scope-qualified `target`. Returns the removed\n   * target. Idempotent — removing a target with no embedding still succeeds\n   * (returns the target).\n   */\n  remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;\n\n  /**\n   * Return the `topK` nearest records to `vector`, in descending score order.\n   */\n  query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;\n}\n\n/**\n * One embedded fragment of a record: the fragment's vector, plus at least one of the\n * two ways to identify it — its advisory in-record {@link IFragmentLocator | span}\n * and/or an opaque consumer-minted {@link IEmbeddedFragment.fragmentId | fragmentId}.\n * Produced by a {@link FragmentEmbedder} and stored via\n * {@link IFragmentVectorIndex.addFragments}.\n *\n * @remarks\n * Both identity fields are optional **in the type**, but the \"at least one\"\n * requirement is real — a fragment carrying neither is unidentifiable at the read\n * side. It is enforced by {@link embeddedFragmentConverter} (and re-checked by the\n * in-package index implementations) rather than by a conditional-required union\n * (`{ locator; fragmentId? } | { locator?; fragmentId }`), which was considered and\n * declined: the union costs at every construction site and buys nothing at the read\n * site, where each field reads as `… | undefined` either way.\n * @public\n */\nexport interface IEmbeddedFragment {\n  /**\n   * The region of the record body this fragment was derived from, when one can be\n   * stated honestly. Advisory — see {@link IFragmentLocator}; it is NOT a slice that\n   * reproduces the fragment text. Omit it for a fragment with no honest body span (a\n   * rewriting segmenter), in which case `fragmentId` must be supplied.\n   */\n  readonly locator?: IFragmentLocator;\n  /**\n   * An opaque, consumer-minted identity for this fragment, carried verbatim through\n   * the index and returned on the corresponding {@link IVectorQueryHit}. The index\n   * **never parses it, never filters on it, and never assigns meaning to it** — it is\n   * a bytestring, not part of the query path. It exists so a fragment stays\n   * identifiable when its text is not re-derivable from the record body.\n   *\n   * The guarantee is \"we never parse it\", NOT \"we keep it stable\". Because\n   * `addFragments` is whole-record-replace, an updated record re-emits its entire\n   * fragment set, so **any stability of a fragment id across re-embeds is the\n   * consumer's responsibility**, not the index's.\n   */\n  readonly fragmentId?: string;\n  /** The embedding vector for this fragment. */\n  readonly vector: Float32Array;\n}\n\n/**\n * The fragment-granular sibling of {@link IVectorIndex}: instead of one vector per\n * record it holds many vectors per record, each tagged with the identity its\n * {@link IEmbeddedFragment} carried, and its `query` returns per-fragment hits\n * carrying that identity back. This is the seam behind sub-document semantic search\n * — the \"discovery\" half of a search-then-read contract, where a hit tells the\n * consumer which record AND which fragment of it to read.\n *\n * @remarks\n * Deliberately NOT `extends IVectorIndex`: an index holding many vectors per record\n * has no well-defined single-vector `add(target, vector)`. It is a parallel contract\n * with three operations — `addFragments`, `remove`, `query` — reusing\n * {@link IVectorQueryHit}, on which both `locator` and `fragmentId` are optional. A\n * fragment hit populates whichever of the two its stored fragment carried; see\n * {@link IVectorQueryHit} for why that is not a discriminator and why fragment-ness\n * is determined by the index queried, not by field presence. Kept distinct from the\n * record-granular index per the consumer contract: memory recall stays\n * record-granular; sub-document knowledge uses a separate fragment index.\n * @public\n */\nexport interface IFragmentVectorIndex {\n  /**\n   * Add (or replace) all fragments for the scope-qualified `target`. Whole-record\n   * semantics: every fragment previously held for `target` is dropped and replaced\n   * by `fragments`, so a re-authored document never leaves stale fragments behind.\n   * Returns the number of fragments now held for the record.\n   */\n  addFragments(target: IEdgeTarget, fragments: ReadonlyArray<IEmbeddedFragment>): Promise<Result<number>>;\n\n  /**\n   * Remove every fragment for the scope-qualified `target`. Returns the removed\n   * target. Idempotent — removing a target with no fragments still succeeds.\n   */\n  remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;\n\n  /**\n   * Return the `topK` nearest fragments to `vector`, in descending score order,\n   * each hit carrying its record `target` plus whichever of `locator` /\n   * `fragmentId` the stored fragment was added with. When\n   * `maxPerRecord` is supplied, no more than that many fragments of any single\n   * record appear in the result — the cap is applied during selection (before the\n   * `topK` cut) so one long document cannot crowd out others.\n   */\n  query(\n    vector: Float32Array,\n    topK: number,\n    maxPerRecord?: number\n  ): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;\n}\n\n/**\n * Embeds a complete record into a vector for the store's embed-on-write hook.\n * Async and `Result`-returning, since a real embedder does a network call (cloud\n * provider) or in-process model inference. The consumer wires this — the core\n * package never calls an embedding provider directly, staying embedder-agnostic.\n * @public\n */\nexport type MemoryEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<Float32Array>>;\n\n/**\n * The fragment-granular sibling of {@link MemoryEmbedder}: chunks a record's body\n * and embeds each chunk, returning one {@link IEmbeddedFragment} per chunk. The\n * chunking policy (window size, overlap) lives entirely in the consumer's embedder\n * — the core stays chunking-agnostic, exactly as it stays embedder-agnostic for\n * the record-granular path. Used by the store's fragment-embed-on-write hook.\n * @public\n */\nexport type FragmentEmbedder = (\n  record: IMemoryRecord<unknown>\n) => Promise<Result<ReadonlyArray<IEmbeddedFragment>>>;\n\n/**\n * A record paired with its scope-qualified {@link IEdgeTarget | address}, as\n * yielded by {@link IMemoryRecordSource.list}. The address is required because\n * {@link InMemoryCosineIndex.rebuild} keys each re-embedded entry on the\n * scope-qualified target, not a bare {@link MemoryId} — two records that share a\n * filename stem across scopes must not collide when the whole vault is re-indexed.\n * @public\n */\nexport interface IScopedMemoryRecord {\n  /** The record's scope-qualified `(scope, id)` address. */\n  readonly target: IEdgeTarget;\n  /** The record itself, passed to the embedder. */\n  readonly record: IMemoryRecord<unknown>;\n}\n\n/**\n * The minimal record-source surface {@link InMemoryCosineIndex.rebuild} reads to\n * re-embed an entire vault. Each entry carries the record's scope-qualified\n * address (see {@link IScopedMemoryRecord}) so the rebuild keys the vector index\n * exactly as the incremental embed-on-write path does. A consumer backs this with\n * the store's scoped index — the vector packlet does not import the store packlet\n * (which depends on the vector packlet for {@link IVectorIndex}, so the reverse\n * import would be a cycle).\n * @public\n */\nexport interface IMemoryRecordSource {\n  /** List every record in the vault, each paired with its scoped address. */\n  list(): Promise<Result<ReadonlyArray<IScopedMemoryRecord>>>;\n}\n"]}
+{"version":3,"file":"vectorIndex.js","sourceRoot":"","sources":["../../../src/packlets/vector/vectorIndex.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result } from '@fgv/ts-utils';\nimport { IEdgeTarget, IMemoryRecord } from '../types';\n\n/**\n * A half-open `[start, end)` span into a record's body — the in-record locator a\n * {@link IFragmentVectorIndex} may carry on a fragment. `start` is inclusive,\n * `end` exclusive. The unit (character / byte / token offsets) is the consumer's\n * choice: the index stores the two integers opaquely and never interprets them,\n * so they line up with whatever locator the consumer's own read side uses.\n *\n * @remarks\n * **The span is advisory.** It names the region of the body a fragment was\n * *derived from*; it is NOT a slice guaranteed to reproduce the fragment's text.\n * `body.slice(start, end)` round-trips only under a segmenter that merely chooses\n * boundaries. Under a **rewriting** segmenter — one that turns a span into a\n * curated block, an increasingly common ingestion shape when a model both selects\n * and rewrites — the fragment text is not a substring of the body at all, and the\n * fragmentation is not re-derivable from the body. Treat the span as a pointer for\n * locating context, never as an extraction recipe.\n *\n * A fragment whose provenance cannot honestly be expressed as a body span should\n * omit the locator entirely and carry an {@link IEmbeddedFragment.fragmentId}\n * instead.\n * @public\n */\nexport interface IFragmentLocator {\n  /** Inclusive start offset into the record body. */\n  readonly start: number;\n  /** Exclusive end offset into the record body. */\n  readonly end: number;\n}\n\n/**\n * A single hit returned by {@link IVectorIndex.query} (or\n * {@link IFragmentVectorIndex.query}): the matched record's scope-qualified\n * {@link IEdgeTarget | address} and the backend's similarity score (higher = more\n * similar; the exact scale is backend-defined). Hits are returned in descending\n * score order.\n *\n * @remarks\n * The address is a `(scope, id)` pair, NOT a bare {@link MemoryId} — per-scope\n * codecs (e.g. the medium-term codec's `turn-<n>` stems) legally mint the same\n * stem under different scopes, so a bare id could not disambiguate two records\n * that share a stem. The caller re-resolves the hit against the record index by\n * the same scoped address.\n *\n * **No single field discriminates a fragment hit from a record-granular hit.** A\n * record hit carries neither `locator` nor `fragmentId`; a fragment hit carries at\n * least one of the two, but not necessarily any particular one — a fragment with a\n * body span but no consumer-minted id, and a fragment with an id but no honest span,\n * are both legal. Testing one field for presence therefore cannot tell you which\n * kind of hit you hold.\n *\n * That \"at least one\" requirement is enforced on the upsert side by\n * {@link embeddedFragmentConverter} — a different boundary from this type — and is\n * deliberately NOT offered here as a discriminator either. A caller keyed off it\n * would be coupled to an invariant this type does not own, and would fail silently\n * if the invariant were ever relaxed.\n *\n * **The robust rule is that fragment-ness is determined by which index produced the\n * hit**: {@link IFragmentVectorIndex.query} returns fragment hits and\n * {@link IVectorIndex.query} returns record hits. The caller chose the index it\n * queried, so it already knows which kind it is holding.\n *\n * Note in particular that an absent `locator` now carries **two** distinct meanings\n * — a record-granular hit, or a fragment with no honest body span (see\n * {@link IFragmentLocator}) — which is precisely why presence-branching is unsafe.\n * @public\n */\nexport interface IVectorQueryHit {\n  /** The scope-qualified address of the matched record. */\n  readonly target: IEdgeTarget;\n  /** Backend similarity score; higher is more similar. */\n  readonly score: number;\n  /**\n   * The advisory in-record span the matched fragment was derived from, when the\n   * producing fragment carried one. Absent on record-granular hits AND on fragment\n   * hits with no honest span — see the remarks above; do not branch on its presence.\n   */\n  readonly locator?: IFragmentLocator;\n  /**\n   * The opaque identity the producing fragment was stored with, carried back\n   * verbatim. Absent on record-granular hits AND on fragment hits stored without\n   * one — see the remarks above; do not branch on its presence.\n   */\n  readonly fragmentId?: string;\n}\n\n/**\n * The vector-index seam an embedding backend implements to make\n * {@link SemanticRetriever | semantic recall} operational.\n *\n * @remarks\n * Vectors cross this seam as `Float32Array` (the in-memory representation an\n * embedding model produces); `number[]` is reserved for the JSON-wire edges\n * (e.g. a provider's embedding response). The in-package brute-force cosine\n * implementation is {@link InMemoryCosineIndex}; a consumer can swap an external\n * ANN backend behind the same seam once N grows beyond the in-memory regime.\n *\n * Every operation returns a `Result` (async, since a real backend does I/O) so\n * failure is explicit and never throws across the seam.\n * @public\n */\nexport interface IVectorIndex {\n  /**\n   * Add (or replace) the embedding for the scope-qualified `target`. Returns the\n   * opaque {@link IMemoryEnvelope.embeddingRef | embeddingRef} the store stamps\n   * onto the envelope so a later read knows the record is embedded. Keying on the\n   * `(scope, id)` address (not a bare id) is load-bearing: two records that share\n   * a filename stem across scopes must not clobber each other's embedding.\n   */\n  add(target: IEdgeTarget, vector: Float32Array): Promise<Result<string>>;\n\n  /**\n   * Remove the embedding for the scope-qualified `target`. Returns the removed\n   * target. Idempotent — removing a target with no embedding still succeeds\n   * (returns the target).\n   */\n  remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;\n\n  /**\n   * Return the `topK` nearest records to `vector`, in descending score order.\n   */\n  query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;\n\n  /**\n   * The number of vectors currently held.\n   *\n   * @remarks\n   * On the contract because without it a caller cannot distinguish *\"the index is\n   * empty\"* from *\"nothing matched\"*: {@link IVectorIndex.query} answers an empty\n   * index with `succeed([])`, which is indistinguishable from a genuine miss. The\n   * only other check available to a caller — \"is a vector index wired?\" — tests the\n   * **wiring**, and that stays true while the index holds nothing.\n   *\n   * Note the narrow scope: this answers *how many vectors are held*, **not** how\n   * many there ought to be. Full coverage — \"is every record that should be indexed\n   * actually indexed?\" — still requires comparing against the record source and\n   * {@link IMemoryStore.embedsKind}.\n   *\n   * Synchronous and non-`Result` because both shipped implementations can answer it\n   * without I/O that can fail — the in-memory index reads a `Map`'s size, and the\n   * SQLite-backed one a prepared `COUNT` against an open connection it already owns.\n   */\n  readonly size: number;\n\n  /**\n   * Re-embed every record from `source` and rebuild the index from scratch — the\n   * **backfill / reconcile** operation.\n   *\n   * @remarks\n   * On the contract because a persisted index is unusable without it. Records\n   * written while the index was unwired, a re-embed after a dimension change (where\n   * the backend supports one — a `vec0`-backed table's dimension is fixed at\n   * creation, so there it needs a drop-and-re-index instead), and reconciliation\n   * after a swallowed embed-on-write failure are all unreachable otherwise — and the store's own docstring already promises *\"the derived index\n   * is reconciled by a later `rebuild`\"*, a promise the contract could not keep for\n   * any index but the bundled one. A caller moving from the bundled implementation\n   * to a persistent one found the swap type-checked everywhere **except** the one\n   * place it backfills, which is the place that mattered.\n   *\n   * See {@link IVectorRebuildReport} for what it reports and\n   * {@link IVectorRebuildOptions} for the failure mode.\n   */\n  rebuild(\n    source: IMemoryRecordSource,\n    embed: MemoryEmbedder,\n    options?: IVectorRebuildOptions\n  ): Promise<Result<IVectorRebuildReport>>;\n}\n\n/**\n * One embedded fragment of a record: the fragment's vector, plus at least one of the\n * two ways to identify it — its advisory in-record {@link IFragmentLocator | span}\n * and/or an opaque consumer-minted {@link IEmbeddedFragment.fragmentId | fragmentId}.\n * Produced by a {@link FragmentEmbedder} and stored via\n * {@link IFragmentVectorIndex.addFragments}.\n *\n * @remarks\n * Both identity fields are optional **in the type**, but the \"at least one\"\n * requirement is real — a fragment carrying neither is unidentifiable at the read\n * side. It is enforced by {@link embeddedFragmentConverter} (and re-checked by the\n * in-package index implementations) rather than by a conditional-required union\n * (`{ locator; fragmentId? } | { locator?; fragmentId }`), which was considered and\n * declined: the union costs at every construction site and buys nothing at the read\n * site, where each field reads as `… | undefined` either way.\n * @public\n */\nexport interface IEmbeddedFragment {\n  /**\n   * The region of the record body this fragment was derived from, when one can be\n   * stated honestly. Advisory — see {@link IFragmentLocator}; it is NOT a slice that\n   * reproduces the fragment text. Omit it for a fragment with no honest body span (a\n   * rewriting segmenter), in which case `fragmentId` must be supplied.\n   */\n  readonly locator?: IFragmentLocator;\n  /**\n   * An opaque, consumer-minted identity for this fragment, carried verbatim through\n   * the index and returned on the corresponding {@link IVectorQueryHit}. The index\n   * **never parses it, never filters on it, and never assigns meaning to it** — it is\n   * a bytestring, not part of the query path. It exists so a fragment stays\n   * identifiable when its text is not re-derivable from the record body.\n   *\n   * The guarantee is \"we never parse it\", NOT \"we keep it stable\". Because\n   * `addFragments` is whole-record-replace, an updated record re-emits its entire\n   * fragment set, so **any stability of a fragment id across re-embeds is the\n   * consumer's responsibility**, not the index's.\n   */\n  readonly fragmentId?: string;\n  /** The embedding vector for this fragment. */\n  readonly vector: Float32Array;\n}\n\n/**\n * The fragment-granular sibling of {@link IVectorIndex}: instead of one vector per\n * record it holds many vectors per record, each tagged with the identity its\n * {@link IEmbeddedFragment} carried, and its `query` returns per-fragment hits\n * carrying that identity back. This is the seam behind sub-document semantic search\n * — the \"discovery\" half of a search-then-read contract, where a hit tells the\n * consumer which record AND which fragment of it to read.\n *\n * @remarks\n * Deliberately NOT `extends IVectorIndex`: an index holding many vectors per record\n * has no well-defined single-vector `add(target, vector)`. It is a parallel contract\n * with three operations — `addFragments`, `remove`, `query` — reusing\n * {@link IVectorQueryHit}, on which both `locator` and `fragmentId` are optional. A\n * fragment hit populates whichever of the two its stored fragment carried; see\n * {@link IVectorQueryHit} for why that is not a discriminator and why fragment-ness\n * is determined by the index queried, not by field presence. Kept distinct from the\n * record-granular index per the consumer contract: memory recall stays\n * record-granular; sub-document knowledge uses a separate fragment index.\n * @public\n */\nexport interface IFragmentVectorIndex {\n  /**\n   * Add (or replace) all fragments for the scope-qualified `target`. Whole-record\n   * semantics: every fragment previously held for `target` is dropped and replaced\n   * by `fragments`, so a re-authored document never leaves stale fragments behind.\n   * Returns the number of fragments now held for the record.\n   */\n  addFragments(target: IEdgeTarget, fragments: ReadonlyArray<IEmbeddedFragment>): Promise<Result<number>>;\n\n  /**\n   * Remove every fragment for the scope-qualified `target`. Returns the removed\n   * target. Idempotent — removing a target with no fragments still succeeds.\n   */\n  remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;\n\n  /**\n   * Return the `topK` nearest fragments to `vector`, in descending score order,\n   * each hit carrying its record `target` plus whichever of `locator` /\n   * `fragmentId` the stored fragment was added with. When\n   * `maxPerRecord` is supplied, no more than that many fragments of any single\n   * record appear in the result — the cap is applied during selection (before the\n   * `topK` cut) so one long document cannot crowd out others.\n   */\n  query(\n    vector: Float32Array,\n    topK: number,\n    maxPerRecord?: number\n  ): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;\n}\n\n/**\n * How a vector-index rebuild treats a record it cannot index — whether the\n * **embedding** failed or the subsequent **add** did. Both are governed by this\n * one mode; neither is unconditionally fatal.\n *\n * @remarks\n * Deliberately mirrors the store's own open-time `onRecordError` mode, including\n * its default: `'fail'` preserves the historical all-or-nothing contract exactly,\n * and `'skip'` is opt-in. Defined here rather than imported from the store packlet\n * — the `vector` packlet does not depend on `store`, and the two modes describe\n * different domains that merely happen to share a shape.\n *\n * A **decline** (a {@link MemoryEmbedder} resolving `undefined`) is not an error\n * and is unaffected by this mode: it is always **excluded** from the index and\n * counted on {@link IVectorRebuildReport.declined}, **never** appearing in\n * {@link IVectorRebuildReport.skipped}. The word is worth being careful with here:\n * `skipped` is now a formal field meaning *a fault*, and a decline is the opposite.\n * @public\n */\nexport type VectorRebuildErrorMode = 'skip' | 'fail';\n\n/**\n * A record a rebuild could not index — because the embed failed or because the\n * subsequent add did — retained so a partial rebuild reports what it lost rather\n * than merely how much it kept.\n * @public\n */\nexport interface ISkippedVectorRecord {\n  /** The scope-qualified address of the record that could not be indexed. */\n  readonly target: IEdgeTarget;\n  /** The failure message, from either the embed or the subsequent add. */\n  readonly error: string;\n}\n\n/**\n * What a rebuild actually did — the structural answer to \"is this index complete?\".\n *\n * @remarks\n * A bare count cannot distinguish the three ways a record can be absent from the\n * index, and that distinction is the entire point: **`declined` was intentional,\n * `skipped` was a fault, and neither is the same as \"never attempted\"**. A caller\n * deriving coverage from a count alone cannot tell an embedder outage from a\n * deliberate policy, which is precisely the confusion this type exists to end.\n * @public\n */\nexport interface IVectorRebuildReport {\n  /** Records embedded and added to the index. */\n  readonly indexed: number;\n  /** Records the embedder deliberately declined (resolved `undefined`). */\n  readonly declined: number;\n  /**\n   * Records whose embedding or add FAILED and were skipped. Non-empty only under\n   * {@link VectorRebuildErrorMode | `onRecordError: 'skip'`} — under `'fail'` the\n   * first failure aborts the rebuild and no report is returned at all.\n   */\n  readonly skipped: ReadonlyArray<ISkippedVectorRecord>;\n}\n\n/**\n * Options for a vector-index rebuild.\n * @public\n */\nexport interface IVectorRebuildOptions {\n  /**\n   * How to treat a record the rebuild cannot index — an embed failure OR an add\n   * failure. Defaults to `'fail'` — the historical behavior, unchanged for every\n   * existing caller.\n   */\n  readonly onRecordError?: VectorRebuildErrorMode;\n}\n\n/**\n * Embeds a complete record into a vector for the store's embed-on-write hook.\n * Async and `Result`-returning, since a real embedder does a network call (cloud\n * provider) or in-process model inference. The consumer wires this — the core\n * package never calls an embedding provider directly, staying embedder-agnostic.\n *\n * @remarks\n * Resolving to `undefined` means **\"intentionally not embedded\"** — a deliberate\n * decline, not an error. The record is stored without an embedding reference, no\n * failure is reported, and **the decline itself logs nothing**. This is distinct\n * from a `Failure`, which means the embedder *tried and could not*.\n *\n * \"Logs nothing\" is a statement about the decline, not a promise of silence: a\n * decline on a record that was already embedded also prunes the vector that\n * reference named, and if that prune fails it is a genuine fault and warns like\n * any other. What a decline never does is warn merely for having happened.\n *\n * The distinction is load-bearing wherever the two are treated differently. On the\n * rebuild path a declined record is **excluded** from the index and counted on\n * {@link IVectorRebuildReport.declined}; a failed one is a genuine error and, under\n * `onRecordError: 'skip'`, is reported on {@link IVectorRebuildReport.skipped}. Collapsing \"I chose not to\" into `fail` would\n * make a deliberate policy indistinguishable from an embedder outage in the logs,\n * and would put a routine decision on whatever error path the caller has wired.\n *\n * The embedder receives the whole record, so the usual reason to decline is the\n * record's `kind` — a control or bookkeeping row that no query should ever return.\n *\n * @public\n */\nexport type MemoryEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<Float32Array | undefined>>;\n\n/**\n * The fragment-granular sibling of {@link MemoryEmbedder}: chunks a record's body\n * and embeds each chunk, returning one {@link IEmbeddedFragment} per chunk. The\n * chunking policy (window size, overlap) lives entirely in the consumer's embedder\n * — the core stays chunking-agnostic, exactly as it stays embedder-agnostic for\n * the record-granular path. Used by the store's fragment-embed-on-write hook.\n * @public\n */\nexport type FragmentEmbedder = (\n  record: IMemoryRecord<unknown>\n) => Promise<Result<ReadonlyArray<IEmbeddedFragment>>>;\n\n/**\n * A record paired with its scope-qualified {@link IEdgeTarget | address}, as\n * yielded by {@link IMemoryRecordSource.list}. The address is required because\n * {@link InMemoryCosineIndex.rebuild} keys each re-embedded entry on the\n * scope-qualified target, not a bare {@link MemoryId} — two records that share a\n * filename stem across scopes must not collide when the whole vault is re-indexed.\n * @public\n */\nexport interface IScopedMemoryRecord {\n  /** The record's scope-qualified `(scope, id)` address. */\n  readonly target: IEdgeTarget;\n  /** The record itself, passed to the embedder. */\n  readonly record: IMemoryRecord<unknown>;\n}\n\n/**\n * The minimal record-source surface {@link InMemoryCosineIndex.rebuild} reads to\n * re-embed an entire vault. Each entry carries the record's scope-qualified\n * address (see {@link IScopedMemoryRecord}) so the rebuild keys the vector index\n * exactly as the incremental embed-on-write path does. A consumer backs this with\n * the store's scoped index — the vector packlet does not import the store packlet\n * (which depends on the vector packlet for {@link IVectorIndex}, so the reverse\n * import would be a cycle).\n * @public\n */\nexport interface IMemoryRecordSource {\n  /** List every record in the vault, each paired with its scoped address. */\n  list(): Promise<Result<ReadonlyArray<IScopedMemoryRecord>>>;\n}\n"]}