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

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.
@@ -407,6 +407,8 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      * contributes nothing.
      */
     private static _projectAsOf;
+    /** {@inheritDoc IMemoryStore.reconcileRank} */
+    reconcileRank(kind: Kind): Promise<Result<number>>;
     /** {@inheritDoc IMemoryStore.put} */
     put(record: IMemoryRecord<unknown>): Promise<Result<IMemoryRecord<unknown>>>;
     /** {@inheritDoc IMemoryStore.delete} */
@@ -457,39 +459,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 +467,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
@@ -634,6 +583,43 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      */
     private _isMutableMetadataUnchanged;
     private _contentHash;
+    /**
+     * The locked body of {@link FileTreeMemoryStore.reconcileRank}.
+     *
+     * @remarks
+     * Re-reads each record's file rather than trusting the in-memory index, for
+     * two reasons: the index holds converted bodies on some paths and raw ones on
+     * others, and re-serializing a *converted* body could change the bytes on disk
+     * — a reconcile of an ordering field has no business rewriting content.
+     * `splitFrontmatter` hands back the body text unconverted, so the round trip
+     * carries the authored characters through untouched and only the envelope
+     * moves. The parsed record is additionally put through `_verifyLoaded`, the
+     * same id-vs-filename and scope-derived-entityId check the load paths apply —
+     * without it, reconcile would be the one path that accepts and rewrites a file
+     * the store would refuse to load.
+     *
+     * "Untouched" is not quite "byte-identical", and the exception is line
+     * endings: `splitFrontmatter` strips a trailing `\r` per line and
+     * `joinFrontmatter` writes `\n` delimiters, so a CRLF-authored file comes back
+     * LF-normalized. That is **the store's behavior on every write path, not
+     * something reconcile introduces** — an ordinary `put` normalizes the same way
+     * — so reconcile does not rewrite content that a subsequent write would have
+     * left alone. The property being claimed here is the narrower and load-bearing
+     * one: no body is round-tripped through its registered Converter.
+     *
+     * The projector is fed an `IMemoryRecord<string>` carrying that raw body,
+     * which is exactly the shape {@link FileTreeMemoryStore._stampRank} hands it
+     * on the write path — so a projector cannot see one thing on a write and
+     * another on a reconcile. `_stampRank` itself is reused verbatim, which also
+     * inherits its throw semantics (logged at `warn`, `rank` cleared).
+     */
+    private _reconcileRankLocked;
+    /**
+     * Re-apply the rank projector to one record on disk. Returns whether `rank`
+     * actually changed — an unchanged rank writes nothing, so a reconcile over an
+     * already-consistent store touches no files.
+     */
+    private _restampOne;
     /**
      * Stamp the store-computed {@link IMemoryEnvelope.rank} onto a fully-built,
      * fully-stamped record by running the kind's registered {@link RankProjector}.
@@ -651,6 +637,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 +1162,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;
     /**
@@ -1664,6 +1683,14 @@ export declare interface IMemoryEnvelope {
      * Absent when the kind has no registered projector (or the projector threw on
      * this record). Ordered retrieval (`orderBy: 'rank'`) and the index's rank view
      * sort by this value descending, placing records with an absent `rank` last.
+     *
+     * **The projector runs on the write path only — registering one does not rank
+     * records already in the store.** Because absent sorts last, those records land
+     * below every subsequently-written one regardless of what the projector would
+     * have scored them, so the result is not a partial ordering but one inverted
+     * with respect to the projector's intent, with nothing failing to say so. Call
+     * `IMemoryStore.reconcileRank` after registering a projector against a
+     * populated store.
      */
     readonly rank?: number;
     /** Structured provenance (never a flat enum). */
@@ -1830,6 +1857,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 +1898,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.
@@ -1924,6 +1963,23 @@ export declare interface IMemoryQuery {
     readonly scope?: MemoryScopeKey;
     /** Restrict to records carrying this tag (exact match). */
     readonly tag?: Tag;
+    /**
+     * Restrict to records whose {@link IProvenance.source | provenance.source} is
+     * exactly this value — the "show me everything this source produced" axis, for
+     * review, attribution, and retraction after a bad ingest.
+     *
+     * @remarks
+     * Exact match on `source` only, deliberately: not a subset match over the whole
+     * {@link IProvenance} block, not a presence check, and not a match on `by` /
+     * `model` / the consumer-owned extension keys. `source` is the only field of
+     * that block the library assigns meaning to, and every record carries one
+     * (`envelope.provenance` is required), so this axis is total — it partitions
+     * the vault rather than filtering out records that merely omit a field.
+     *
+     * Applied in the shared pre-filter alongside `scope` / `kind` / `tag`, so every
+     * retriever honours it and combining axes composes as AND.
+     */
+    readonly provenanceSource?: ProvenanceSource;
     /**
      * Restrict to records of this kind — the single-kind shorthand for
      * {@link IMemoryQuery.kinds | kinds}. When both are set they compose as AND
@@ -1984,7 +2040,7 @@ export declare interface IMemoryQuery {
      * empty page, never a throw.
      */
     readonly offset?: number;
-    /** Arbitrary predicate applied after the scope / kind / tag pre-filter. */
+    /** Arbitrary predicate applied after the scope / kind / tag / provenance-source pre-filter. */
     readonly filter?: (record: IMemoryRecord<unknown>) => boolean;
 }
 
@@ -2083,8 +2139,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 +2181,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
@@ -2125,6 +2208,36 @@ export declare interface IMemoryStore {
      * existing record unchanged on a dedup no-op.
      */
     put(record: IMemoryRecord<unknown>): Promise<Result<IMemoryRecord<unknown>>>;
+    /**
+     * Re-apply the kind's {@link RankProjector} to every record of `kind` already
+     * in the store, restamping {@link IMemoryEnvelope.rank}. Returns the number of
+     * records whose `rank` actually changed.
+     *
+     * @remarks
+     * **This exists because `rank` is otherwise new-store-only, and fails in a way
+     * that looks like it works.** The projector runs on the write path only, so
+     * registering one against a populated store ranks nothing already written —
+     * and because an absent `rank` sorts *last*, every pre-registration record
+     * lands below every post-registration one no matter what the projector would
+     * have scored it. The ordering is not merely partial; it is **inverted with
+     * respect to the projector's own intent**, with no failure anywhere to say so.
+     *
+     * Deliberately **does not** touch `created` / `updated` / `seq`, and fires no
+     * `'write'` observation. Routing a reconcile through {@link IMemoryStore.put}
+     * would bump transaction time on every record — trading a wrong `rank` order
+     * for a wrong recency order, and flooding any wired observer with writes that
+     * are not writes. The body is re-serialized verbatim from the file's own
+     * bytes; only the envelope's `rank` moves.
+     *
+     * Fails loudly if `kind` has no registered projector: asking to reconcile a
+     * kind you never configured is a caller error, not a no-op.
+     *
+     * **Not atomic, and safe for it.** A failure part-way leaves earlier records
+     * restamped. That is benign because restamping is idempotent — re-running
+     * converges — which is also why no report shape is offered here. A count is
+     * enough.
+     */
+    reconcileRank(kind: Kind): Promise<Result<number>>;
     /**
      * Delete a record by `(kind, entityId)`. Non-temporal kinds physically delete
      * the file and return the deleted record's {@link MemoryId}. Temporal
@@ -2204,9 +2317,10 @@ export declare interface IMergeStrategy {
 }
 
 /**
- * Whether an indexed entry satisfies a query's scope / kind / tag / predicate
- * pre-filter (the axes shared by every v1 retriever). The `semantic` / `asOf` /
- * link axes are NOT applied here — those are each retriever's own concern.
+ * Whether an indexed entry satisfies a query's scope / kind / tag /
+ * provenance-source / predicate pre-filter (the axes shared by every v1
+ * retriever). The `semantic` / `asOf` / link axes are NOT applied here — those
+ * are each retriever's own concern.
  * @public
  */
 export declare function indexedRecordMatchesQuery(entry: IIndexedMemoryRecord, query: IMemoryQuery): boolean;
@@ -2269,17 +2383,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.
      *
-     * 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.
+     * @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.
+     *
+     * 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 +2487,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 +2639,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 +2769,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 +2866,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
@@ -2891,7 +3124,7 @@ export declare const LINK_TRAVERSAL_UNWIRED_MESSAGE: string;
  *   is the exact, collision-free cycle key — no structural hashing (e.g.
  *   `Crc32Normalizer`) is needed. A self-loop or any multi-hop cycle terminates
  *   because a revisited node is never re-expanded.
- * - **Post-filter.** The scope / kind / tag / predicate axes of the query are
+ * - **Post-filter.** The scope / kind / tag / provenance-source / predicate axes of the query are
  *   applied to the reached records (the link axes are the traversal itself).
  * @public
  */
@@ -3019,9 +3252,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>>;
+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 MemoryEmbedOutcome = 'embedded' | 'declined' | 'excluded' | 'failed';
 
 /**
  * Stable file-stem identifier for a memory record. Equals the codec-produced
@@ -3557,6 +3862,9 @@ export declare function rankCompare(a: IMemoryRecord<unknown>, b: IMemoryRecord<
  * {@link IMemoryEnvelope.rank}. The store never interprets the body — the host
  * owns what the number means. A projector that throws is treated as "no rank
  * for this record" (logged at `warn`), never failing the write.
+ *
+ * Runs on writes only. To apply a newly-registered projector to records that
+ * already exist, call `IMemoryStore.reconcileRank`.
  * @public
  */
 export declare type RankProjector = (record: IMemoryRecord<unknown>) => number;
@@ -3569,7 +3877,7 @@ export declare type RankProjector = (record: IMemoryRecord<unknown>) => number;
 export declare function recencyCompare(a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>): number;
 
 /**
- * Returns records matching the query's scope / kind / tag / predicate filters,
+ * Returns records matching the query's scope / kind / tag / provenance-source / predicate filters,
  * ordered most-recently-updated first. The universal v1 retriever — an empty
  * query returns the whole vault in recency order.
  * @public
@@ -3627,8 +3935,9 @@ export declare class ScoreUnionMergeStrategy implements IMergeStrategy {
 }
 
 /**
- * Apply the shared scope / kind / tag / predicate pre-filter to a set of indexed
- * entries, returning the surviving records (unordered, unlimited).
+ * Apply the shared scope / kind / tag / provenance-source / predicate pre-filter
+ * to a set of indexed entries, returning the surviving records (unordered,
+ * unlimited).
  * @public
  */
 export declare function selectByQuery(entries: ReadonlyArray<IIndexedMemoryRecord>, query: IMemoryQuery): IMemoryRecord<unknown>[];
@@ -3711,10 +4020,32 @@ export declare function splitFrontmatter(raw: string): Result<IMemoryFileParts>;
 export declare type StoreStampedEnvelopeField = 'id' | 'seq' | 'contentHash' | 'created' | 'updated';
 
 /**
- * Returns records matching `query.filter`, narrowed by any scope / kind / tag
- * pre-filter and recency-ordered. The predicate is this retriever's axis: a
- * query without a `filter` is not its concern and yields an empty success (so it
- * contributes nothing to a {@link HybridRetriever}, rather than failing).
+ * Returns records matching `query.filter` or `query.provenanceSource`, narrowed
+ * by any scope / kind / tag / provenance-source pre-filter and recency-ordered.
+ * Those two are this retriever's axes: a query carrying neither is not its
+ * concern and yields an empty success (so it contributes nothing to a
+ * {@link HybridRetriever}, rather than failing).
+ *
+ * Note `provenanceSource` appears on both sides of that sentence, and the
+ * duplication is real rather than sloppy: it is one of this retriever's two
+ * *dispatch* axes (it decides whether the query is this retriever's concern at
+ * all) **and** a member of the shared *pre-filter* (it narrows the result set,
+ * as it does for every other retriever). `filter` is likewise both.
+ *
+ * @remarks
+ * `provenanceSource` is *applied* by the shared pre-filter, so every retriever
+ * narrows by it. What this retriever adds is *answering* a query whose only axis
+ * is `provenanceSource` — the "show me everything this source produced" request,
+ * which would otherwise fall through the `filter`-absent guard and come back
+ * empty.
+ *
+ * Consequently, inside a {@link HybridRetriever} composed with the universal
+ * {@link RecencyRetriever}, a `provenanceSource`-only query is answered by both
+ * children and every matching record scores twice under a score-union merge.
+ * That is the established behavior for a dedicated-axis retriever composed with
+ * the universal one — {@link TagRetriever} double-scores a `tag`-only query the
+ * same way — and is intentional here, not an artifact of grafting a second axis
+ * onto a retriever whose original concern was arbitrary predicates.
  * @public
  */
 export declare class StructuredFilterRetriever implements IMemoryRetriever {
@@ -3736,7 +4067,7 @@ export declare type Tag = Brand<string, 'Tag'>;
 
 /**
  * Returns records carrying `query.tag`, recency-ordered within the tag and
- * narrowed by any scope / kind / predicate filters. Tag is this retriever's
+ * narrowed by any scope / kind / provenance-source / predicate filters. Tag is this retriever's
  * axis: a query without a `tag` is not its concern and yields an empty success
  * (so it contributes nothing to a {@link HybridRetriever}, rather than failing).
  * @public
@@ -3870,4 +4201,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 { }