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

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"]}

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

@@ -329,6 +329,8 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
     private readonly _writePolicies;
     private readonly _codecs;
     private readonly _rankProjectors;
+    /** `undefined` = no declaration = every kind participates. */
+    private readonly _embedKinds;
     private readonly _defaultCodec;
     private readonly _defaultPolicy;
     private readonly _scopeEncoding;
@@ -336,11 +338,9 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
     private readonly _index;
     private readonly _hasher;
     private readonly _observers;
+    /** Record- and fragment-vector maintenance; every operation is best-effort. */
+    private readonly _vectors;
     private readonly _logger;
-    private readonly _vectorIndex;
-    private readonly _embed;
-    private readonly _fragmentIndex;
-    private readonly _fragmentEmbedder;
     /**
      * Records the initial walk could not load. Populated during `create()` in
      * {@link MemoryRecordErrorMode | `'skip'` mode}; empty otherwise.
@@ -457,39 +457,6 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      * later eviction failure never loses data with nothing written in its place.
      */
     private _admitWrite;
-    /**
-     * Best-effort embed-on-write. When a vector index AND an embedder are wired,
-     * embeds the built record, `add`s the vector (replace semantics handle a same-id
-     * re-embed — no explicit remove), and stamps the returned `embeddingRef`. A
-     * failure (returned `fail` OR a thrown/rejected hook) is logged and the
-     * unembedded record is returned unchanged — the put still persists, and the
-     * derived index is reconciled by a later `rebuild`. A pass-through no-op when
-     * unwired (byte-identical record).
-     *
-     * Always succeeds (`Result` is the chain's shape, never a vector-induced
-     * failure).
-     */
-    private _embedOnWrite;
-    /**
-     * Best-effort fragment-embed-on-write. When a fragment index AND a fragment
-     * embedder are wired, chunks + embeds the built record and replaces its
-     * fragments in the index (`addFragments` is whole-record-replace, so a re-authored
-     * document never leaves stale fragments behind — no explicit remove needed). A
-     * failure (returned `fail` OR a thrown/rejected hook) is logged and the record is
-     * returned unchanged — the put still persists, and the fragment index is a derived
-     * view a later `rebuild` reconciles. Unlike {@link FileTreeMemoryStore._embedOnWrite}
-     * it stamps nothing on the record (fragments have no per-record `embeddingRef`
-     * analog). A pass-through no-op when unwired (byte-identical record).
-     */
-    private _embedFragmentsOnWrite;
-    /**
-     * Best-effort fragment removal. A no-op unless the full fragment lifecycle is
-     * wired (both an index AND an embedder), so an unwired store does no fragment
-     * work and behaves byte-identically. Failures are logged, never surfaced — a
-     * committed delete/eviction must not fail because a derived fragment index could
-     * not be pruned.
-     */
-    private _removeFragmentsBestEffort;
     /**
      * Evict the records named by a `cull-oldest` decision, best-effort. Runs only
      * after the authoritative `_persist`, so a failed eviction is logged (never
@@ -498,26 +465,6 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      * `accept` / `reject` decisions evict nothing.
      */
     private _applyEvictions;
-    /**
-     * Best-effort vector removal for each evicted record (never fails the put).
-     * Every evicted record is in the same `scope` as the incoming write (the
-     * cull-oldest cohort is the incoming record's `(scope, kind)` cohort), so that
-     * scope qualifies each removal target.
-     */
-    private _removeEvictedVectors;
-    /**
-     * Run a consumer-supplied vector hook, normalizing a thrown/rejected hook into a
-     * `Failure` and logging any failure at `warn`. Best-effort: the caller proceeds
-     * regardless, since the index is rebuildable.
-     */
-    private _tryVectorOp;
-    /**
-     * Best-effort vector removal. A no-op unless the full vector lifecycle is wired
-     * (both an index AND an embedder), so an unwired store does no vector work and
-     * behaves byte-identically. Failures are logged, never surfaced — a committed
-     * delete/eviction must not fail because a derived index could not be pruned.
-     */
-    private _removeVectorBestEffort;
     /**
      * Build the record to persist. On a first write the incoming envelope is the
      * base (final content equals the incoming content, so the dedup `hash` is
@@ -651,6 +598,8 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
     private _policyFor;
     /** {@inheritDoc IMemoryStore.dedupScopeFor} */
     dedupScopeFor(kind: Kind): DedupScope;
+    /** {@inheritDoc IMemoryStore.embedsKind} */
+    embedsKind(kind: Kind): boolean;
     /**
      * Read and validate the record at `<scope>/<idStem>.md`, returning `undefined`
      * when the scope directory or file is absent. Verifies the on-disk id ↔
@@ -1174,6 +1123,37 @@ export declare interface IFileTreeMemoryStoreCreateParams {
      * guard-host-callbacks conventions).
      */
     readonly rankProjectors?: ReadonlyMap<Kind, RankProjector>;
+    /**
+     * The kinds whose records participate in the **record-granular** vector index.
+     *
+     * @remarks
+     * **Absent means every kind participates**, which is the pre-existing behavior —
+     * so omitting this is byte-identical to before it existed. Supplying it makes the
+     * set an allowlist: a kind outside it is never handed to the {@link MemoryEmbedder}
+     * on write, and is omitted from {@link IMemoryStore.asRecordSource | asRecordSource},
+     * so a rebuild driven from this store does not pay for it either.
+     *
+     * Two costs motivate it, and the second is the one that is easy to miss:
+     *
+     * - **Embedder work on the critical path.** Embed-on-write is synchronous with
+     *   the write. A bookkeeping row — a status, a counter, a lease — that no query
+     *   will ever return still pays a full embedding round trip, and on a
+     *   locally-hosted model the first call after a restart pays a cold model load
+     *   on top.
+     * - **Un-queried kinds crowd the `topK` window.** `IVectorIndex.query` applies
+     *   `topK` *before* any kind filter the retriever adds, so vectors that can never
+     *   be returned still occupy candidate slots. Over-fetching to compensate hides
+     *   this until the un-queried kinds start scoring well — at which point recall is
+     *   silently lost. Restricting what is indexed fixes the recall problem, not just
+     *   the cost.
+     *
+     * Applies to the record-granular path only. The fragment path
+     * ({@link IFileTreeMemoryStoreCreateParams.fragmentIndex | fragmentIndex} /
+     * `fragmentEmbedder`) is independent and unaffected — a kind may legitimately be
+     * fragment-embedded and not record-embedded, which is the right shape for a long
+     * document whose whole body exceeds the model's context.
+     */
+    readonly embedKinds?: ReadonlySet<Kind>;
     /** Default codec for kinds without an explicit entry. */
     readonly defaultCodec?: IIdentityCodec;
     /**
@@ -1830,6 +1810,12 @@ export declare interface IMemoryObservationQuery {
     readonly phase?: MemoryObservationPhase;
     /** Only records with this outcome. */
     readonly outcome?: MemoryObservationOutcome;
+    /**
+     * Only `'write'` records with this embed outcome. Records carrying no embed
+     * outcome never match, so `embed: 'failed'` answers "which writes left the
+     * index short?" without a full scan of every record's `embeddingRef`.
+     */
+    readonly embed?: MemoryEmbedOutcome;
 }
 
 /**
@@ -1865,6 +1851,12 @@ export declare interface IMemoryObservationRecord {
     readonly error?: string;
     /** Structured provenance of the write, when the operation carried one. */
     readonly provenance?: IProvenance;
+    /**
+     * For `'write'` observations: what the record-granular vector index did about
+     * this record. Absent when the question does not apply — see
+     * {@link MemoryEmbedOutcome}.
+     */
+    readonly embed?: MemoryEmbedOutcome;
     /**
      * For `'retrieve'` observations: an opaque snapshot of the query that drove
      * the retrieval. Carried verbatim; never interpreted by the store.
@@ -2083,8 +2075,16 @@ export declare interface IMemoryStore {
     /**
      * Adapt this store to the {@link IMemoryRecordSource} seam so it can drive
      * {@link IVectorIndex} rebuilds (e.g. `InMemoryCosineIndex.rebuild`). The
-     * returned source's `list()` delegates to {@link IMemoryStore.listScoped}. The
-     * store cannot implement {@link IMemoryRecordSource} directly because its
+     * returned source's `list()` delegates to {@link IMemoryStore.listScoped},
+     * **filtered to the kinds {@link IMemoryStore.embedsKind | embedsKind} reports** —
+     * this source exists to feed the record vector index, so a kind excluded from
+     * that index is excluded here too, and a reopen does not re-embed records the
+     * index will never return. With no
+     * {@link IFileTreeMemoryStoreCreateParams.embedKinds | embedKinds} declaration
+     * every kind participates and the filter is the identity. `listScoped` itself is
+     * **not** filtered and remains the whole-vault surface.
+     *
+     * The store cannot implement {@link IMemoryRecordSource} directly because its
      * `list(filter?)` returns bare records (the ergonomic query surface) while the
      * seam's `list()` returns scope-qualified records.
      */
@@ -2117,6 +2117,25 @@ export declare interface IMemoryStore {
      * invoking admission or merge logic out of band.
      */
     dedupScopeFor(kind: Kind): DedupScope;
+    /**
+     * Whether records of `kind` participate in the **record-granular** vector index.
+     *
+     * @remarks
+     * A read accessor over the store's injected {@link IFileTreeMemoryStoreCreateParams.embedKinds | embedKinds}
+     * declaration, in the same spirit as {@link IMemoryStore.dedupScopeFor} — one
+     * place to ask, so the store's write path and any caller reasoning about index
+     * coverage cannot disagree. `true` for every kind when no declaration was made.
+     *
+     * **This is distinct from a {@link MemoryEmbedder} decline, and the difference is
+     * cost.** An embedder that returns `undefined` has already been called: the
+     * round trip is paid, and on a locally-hosted model that round trip is the
+     * expense. A kind excluded here is never handed to the embedder at all. The
+     * decline makes the intent *expressible*; this makes it *free*.
+     *
+     * Deliberately synchronous, total, and NOT `Result`-returning: it reads
+     * constructor-injected configuration, touches no I/O, and cannot fail.
+     */
+    embedsKind(kind: Kind): boolean;
     /**
      * Write a record. Validates the body, computes a content hash, deduplicates
      * (scope-wide, before policy), applies the kind's {@link IWritePolicy}, stamps
@@ -2269,17 +2288,40 @@ export declare class InMemoryCosineIndex implements IVectorIndex {
     /**
      * Re-embed every record from `source` and rebuild the index from scratch.
      * Clears the current contents (and the established dimension) first, so a
-     * re-embed with a different model is supported. Returns the number of vectors
-     * indexed.
+     * re-embed with a different model is supported. Returns an
+     * {@link IVectorRebuildReport} describing what was indexed, declined and skipped.
+     *
+     * @remarks
+     * **A failure to LIST is always fatal**, under either mode — and **leaves the
+     * existing index untouched**: an unreadable source says nothing about which
+     * records exist, so there is neither an honest partial to report nor any reason
+     * to discard what is already held.
+     *
+     * Per-record embed/add failures are governed by
+     * {@link IVectorRebuildOptions.onRecordError}, which defaults to `'fail'` —
+     * **the historical all-or-nothing contract, unchanged**: the index is rolled back
+     * to empty rather than left partially rebuilt, so a caller that retries a query
+     * sees a clean empty index it can reason about.
+     *
+     * `'skip'` opts into the lenient shape the store's own open already uses: the
+     * rebuild continues and every casualty is returned structurally on
+     * {@link IVectorRebuildReport.skipped}. **It reports more, it does not report
+     * less** — the point is to stop one bad record emptying an entire index, not to
+     * make failures quieter. A caller that ignores `skipped` under `'skip'` has
+     * chosen to, rather than been given no way to know.
      *
-     * On any failure (list, embed, or add) the index is rolled back to empty
-     * rather than left in a partially-rebuilt state — a caller that retries a query
-     * after a failed rebuild sees a clean empty index, never a half-populated one.
+     * A {@link MemoryEmbedder} decline is not a failure under either mode: it is
+     * counted on {@link IVectorRebuildReport.declined} and never appears in `skipped`.
+     *
+     * Both consumer-supplied hooks are capture-wrapped, so a `source` or `embed`
+     * that throws or rejects becomes a `Failure` on the path above rather than an
+     * exception escaping mid-rebuild — which would bypass the rollback entirely.
      *
      * @param source - The scope-qualified record source to re-embed.
      * @param embed - The embedder applied to each record.
+     * @param options - Rebuild options; omit for the historical `'fail'` behavior.
      */
-    rebuild(source: IMemoryRecordSource, embed: MemoryEmbedder): Promise<Result<number>>;
+    rebuild(source: IMemoryRecordSource, embed: MemoryEmbedder, options?: IVectorRebuildOptions): Promise<Result<IVectorRebuildReport>>;
     /** Empty the index and forget the established dimension. */
     private _reset;
     /** The Euclidean magnitude (L2 norm) of a vector. */
@@ -2350,6 +2392,13 @@ export declare class InMemoryFragmentCosineIndex implements IFragmentVectorIndex
      * On any failure (list, embed, or add) the index is rolled back to empty rather
      * than left in a partially-rebuilt state.
      *
+     * @remarks
+     * **Deliberately still returns a bare count**, unlike the record-granular
+     * {@link InMemoryCosineIndex.rebuild}, which reports an
+     * {@link IVectorRebuildReport}. The asymmetry is scope, not oversight: the
+     * fragment path is tracked separately and gains the same treatment when the
+     * `IVectorIndex`/`IFragmentVectorIndex` contracts are revisited together.
+     *
      * @param source - The scope-qualified record source to re-embed.
      * @param embed - The fragment embedder applied to each record.
      */
@@ -2495,6 +2544,19 @@ export declare interface ISkippedRecord {
     readonly error: string;
 }
 
+/**
+ * A record a rebuild could not index — because the embed failed or because the
+ * subsequent add did — retained so a partial rebuild reports what it lost rather
+ * than merely how much it kept.
+ * @public
+ */
+export declare interface ISkippedVectorRecord {
+    /** The scope-qualified address of the record that could not be indexed. */
+    readonly target: IEdgeTarget;
+    /** The failure message, from either the embed or the subsequent add. */
+    readonly error: string;
+}
+
 /**
  * Narrow an {@link IIdentityCodec} to {@link ITemporalIdentityCodec} by probing
  * for the versioned methods. Used by the store when an `encode` result reports
@@ -2612,6 +2674,45 @@ export declare interface IVectorIndex {
      * Return the `topK` nearest records to `vector`, in descending score order.
      */
     query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    /**
+     * The number of vectors currently held.
+     *
+     * @remarks
+     * On the contract because without it a caller cannot distinguish *"the index is
+     * empty"* from *"nothing matched"*: {@link IVectorIndex.query} answers an empty
+     * index with `succeed([])`, which is indistinguishable from a genuine miss. The
+     * only other check available to a caller — "is a vector index wired?" — tests the
+     * **wiring**, and that stays true while the index holds nothing.
+     *
+     * Note the narrow scope: this answers *how many vectors are held*, **not** how
+     * many there ought to be. Full coverage — "is every record that should be indexed
+     * actually indexed?" — still requires comparing against the record source and
+     * {@link IMemoryStore.embedsKind}.
+     *
+     * Synchronous and non-`Result` because both shipped implementations can answer it
+     * without I/O that can fail — the in-memory index reads a `Map`'s size, and the
+     * SQLite-backed one a prepared `COUNT` against an open connection it already owns.
+     */
+    readonly size: number;
+    /**
+     * Re-embed every record from `source` and rebuild the index from scratch — the
+     * **backfill / reconcile** operation.
+     *
+     * @remarks
+     * On the contract because a persisted index is unusable without it. Records
+     * written while the index was unwired, a re-embed after a dimension change (where
+     * the backend supports one — a `vec0`-backed table's dimension is fixed at
+     * creation, so there it needs a drop-and-re-index instead), and reconciliation
+     * after a swallowed embed-on-write failure are all unreachable otherwise — and the store's own docstring already promises *"the derived index
+     * is reconciled by a later `rebuild`"*, a promise the contract could not keep for
+     * any index but the bundled one. A caller moving from the bundled implementation
+     * to a persistent one found the swap type-checked everywhere **except** the one
+     * place it backfills, which is the place that mattered.
+     *
+     * See {@link IVectorRebuildReport} for what it reports and
+     * {@link IVectorRebuildOptions} for the failure mode.
+     */
+    rebuild(source: IMemoryRecordSource, embed: MemoryEmbedder, options?: IVectorRebuildOptions): Promise<Result<IVectorRebuildReport>>;
 }
 
 /**
@@ -2670,6 +2771,43 @@ export declare interface IVectorQueryHit {
     readonly fragmentId?: string;
 }
 
+/**
+ * Options for a vector-index rebuild.
+ * @public
+ */
+export declare interface IVectorRebuildOptions {
+    /**
+     * How to treat a record the rebuild cannot index — an embed failure OR an add
+     * failure. Defaults to `'fail'` — the historical behavior, unchanged for every
+     * existing caller.
+     */
+    readonly onRecordError?: VectorRebuildErrorMode;
+}
+
+/**
+ * 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.
+ * @public
+ */
+export declare interface IVectorRebuildReport {
+    /** Records embedded and added to the index. */
+    readonly indexed: number;
+    /** Records the embedder deliberately declined (resolved `undefined`). */
+    readonly declined: 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.
+     */
+    readonly skipped: ReadonlyArray<ISkippedVectorRecord>;
+}
+
 /**
  * A per-kind write policy, injected at store construction. Invoked AFTER
  * content-hash dedup (dedup is always pre-policy). The policy decides
@@ -3019,9 +3157,81 @@ export declare type MemoryDetailTier = 'gist' | 'full';
  * Async and `Result`-returning, since a real embedder does a network call (cloud
  * provider) or in-process model inference. The consumer wires this — the core
  * package never calls an embedding provider directly, staying embedder-agnostic.
+ *
+ * @remarks
+ * Resolving to `undefined` means **"intentionally not embedded"** — a deliberate
+ * decline, not an error. The record is stored without an embedding reference, no
+ * failure is reported, and **the decline itself logs nothing**. This is distinct
+ * from a `Failure`, which means the embedder *tried and could not*.
+ *
+ * "Logs nothing" is a statement about the decline, not a promise of silence: a
+ * decline on a record that was already embedded also prunes the vector that
+ * reference named, and if that prune fails it is a genuine fault and warns like
+ * any other. What a decline never does is warn merely for having happened.
+ *
+ * The distinction is load-bearing wherever the two are treated differently. On the
+ * rebuild path a declined record is **excluded** from the index and counted on
+ * {@link IVectorRebuildReport.declined}; a failed one is a genuine error and, under
+ * `onRecordError: 'skip'`, is reported on {@link IVectorRebuildReport.skipped}. Collapsing "I chose not to" into `fail` would
+ * make a deliberate policy indistinguishable from an embedder outage in the logs,
+ * and would put a routine decision on whatever error path the caller has wired.
+ *
+ * The embedder receives the whole record, so the usual reason to decline is the
+ * record's `kind` — a control or bookkeeping row that no query should ever return.
+ *
+ * @public
+ */
+export declare type MemoryEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<Float32Array | undefined>>;
+
+/**
+ * What the record-granular vector index did about a written record.
+ *
+ * @remarks
+ * This exists because **`embeddingRef` absence is three-ways ambiguous**: a
+ * record with no reference may have been declined, excluded, or genuinely
+ * failed to embed, and the `put`'s own `outcome` cannot tell you which — it is
+ * `'success'` in all three, because embed-on-write is best-effort by design and
+ * never fails a durable write. Deriving index coverage from the absent field
+ * alone therefore cannot distinguish a policy decision from an outage.
+ *
+ * - `'embedded'` — embedded and added; the record carries an `embeddingRef`.
+ * - `'declined'` — the {@link MemoryEmbedder} resolved `undefined`: deliberately
+ *   not embedded. Not a fault.
+ * - `'excluded'` — the record's kind is outside the store's `embedKinds`
+ *   declaration, so the embedder was never called. Also not a fault, and the
+ *   cheaper of the two.
+ * - `'failed'` — the embedder returned a `Failure` (or threw), **or** the index
+ *   `add` did. Both are faults, and what they leave behind depends on whether
+ *   the record had been embedded before: a **first** write ends up with no
+ *   `embeddingRef` and nothing in the index, while an **update** keeps the
+ *   reference and vector it already had — so the index goes on answering on the
+ *   record's **previous** content until a `rebuild` reconciles it. Stale, not
+ *   absent. The store's diagnostic logger names which fault it was, because the
+ *   remediation differs (an embedder outage versus an index outage) while the
+ *   coverage answer — "this record needs a re-embed" — does not.
+ *
+ * Absent on a write observation means **no outcome is being reported**, which
+ * covers three cases:
+ *
+ * 1. no vector index / embedder is wired, so there is no index for the record to
+ *    be absent from;
+ * 2. the `put` was a dedup no-op, which attempted nothing;
+ * 3. the `put` **failed** (`outcome: 'failure'`). An embed step may well have run
+ *    before the failure — a record can even have been added to the index and then
+ *    lost its durable write, leaving an orphan vector that a later `rebuild`
+ *    reconciles. That is deliberately not reported here: the field answers
+ *    "is this *stored* record in the index?", and on a failed write there is no
+ *    stored record for it to be a statement about.
+ *
+ * So `embed` is a property of successful writes. Never present on `'read'` /
+ * `'delete'` / `'retrieve'`.
+ *
+ * Record-granular only. The fragment path is independent and reports nothing
+ * here — a record may be fragment-embedded while its record-level outcome is
+ * `'excluded'`.
  * @public
  */
-export declare type MemoryEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<Float32Array>>;
+export declare type MemoryEmbedOutcome = 'embedded' | 'declined' | 'excluded' | 'failed';
 
 /**
  * Stable file-stem identifier for a memory record. Equals the codec-produced
@@ -3870,4 +4080,25 @@ export declare class TemporalVersionedPolicy implements IWritePolicy {
     private _rebuild;
 }
 
+/**
+ * How a vector-index rebuild treats a record it cannot index — whether the
+ * **embedding** failed or the subsequent **add** did. Both are governed by this
+ * one mode; neither is unconditionally fatal.
+ *
+ * @remarks
+ * Deliberately mirrors the store's own open-time `onRecordError` mode, including
+ * its default: `'fail'` preserves the historical all-or-nothing contract exactly,
+ * and `'skip'` is opt-in. Defined here rather than imported from the store packlet
+ * — the `vector` packlet does not depend on `store`, and the two modes describe
+ * different domains that merely happen to share a shape.
+ *
+ * A **decline** (a {@link MemoryEmbedder} resolving `undefined`) is not an error
+ * and is unaffected by this mode: it is always **excluded** from the index and
+ * counted on {@link IVectorRebuildReport.declined}, **never** appearing in
+ * {@link IVectorRebuildReport.skipped}. The word is worth being careful with here:
+ * `skipped` is now a formal field meaning *a fault*, and a decline is the opposite.
+ * @public
+ */
+export declare type VectorRebuildErrorMode = 'skip' | 'fail';
+
 export { }

package/lib/packlets/ingest/orchestrator.d.ts.map

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

package/lib/packlets/ingest/orchestrator.js

@@ -246,7 +246,17 @@ class MemoryIngestOrchestrator {
         if (embedded.isFailure()) {
             return (0, ts_utils_1.fail)(embedded.message);
         }
-        const queried = await this._capture(() => wiring.vectorIndex.query(embedded.value, this._similarityTopK), `ingest '${candidate.envelope.entityId}': similarity query`);
+        // The embedder deliberately declined this candidate, so there is no vector to
+        // search with and layer-2 similarity dedup cannot run for it. That is the same
+        // position as a search that found nothing similar — `'new'` — and not an
+        // error: declining to embed a kind must not make it un-ingestable.
+        if (embedded.value === undefined) {
+            return (0, ts_utils_1.succeed)({ verdict: 'new' });
+        }
+        // Hoisted: the `undefined` check above does not narrow across the callback
+        // boundary below, and a local keeps the non-null assertion out of the code.
+        const vector = embedded.value;
+        const queried = await this._capture(() => wiring.vectorIndex.query(vector, this._similarityTopK), `ingest '${candidate.envelope.entityId}': similarity query`);
         if (queried.isFailure()) {
             return (0, ts_utils_1.fail)(queried.message);
         }