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

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

@@ -1,6 +1,7 @@
 import { AiAssist } from '@fgv/ts-extras';
 import { Brand } from '@fgv/ts-utils';
 import { Converter } from '@fgv/ts-utils';
+import { DetailedResult } from '@fgv/ts-utils';
 import { FileTree } from '@fgv/ts-json-base';
 import { JsonSchema } from '@fgv/ts-json-base';
 import { Logging } from '@fgv/ts-utils';
@@ -31,11 +32,12 @@ export declare type AdmissionDecision = {
  */
 export declare class AsOfRetriever implements IMemoryRetriever {
     private readonly _index;
+    private readonly _resolver;
     private constructor();
     /** {@inheritDoc IMemoryRetriever.capabilities} */
     get capabilities(): IMemoryRetrieverCapabilities;
     /** Family-convention factory. */
-    static create(index: IMemoryIndex): Result<AsOfRetriever>;
+    static create(params: IRetrieverCreateParams): Result<AsOfRetriever>;
     /** {@inheritDoc IMemoryRetriever.retrieve} */
     retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
 }
@@ -164,11 +166,12 @@ export declare function createMemoryTools(params: ICreateMemoryToolsParams): Rea
  */
 export declare class CurrentValidRetriever implements IMemoryRetriever {
     private readonly _index;
+    private readonly _resolver;
     private constructor();
     /** {@inheritDoc IMemoryRetriever.capabilities} */
     get capabilities(): IMemoryRetrieverCapabilities;
     /** Family-convention factory. */
-    static create(index: IMemoryIndex): Result<CurrentValidRetriever>;
+    static create(params: IRetrieverCreateParams): Result<CurrentValidRetriever>;
     /** {@inheritDoc IMemoryRetriever.retrieve} */
     retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
 }
@@ -245,6 +248,22 @@ export declare const DEFAULT_SIMILARITY_TOP_K: number;
  */
 export declare function defaultMemoryScopeEncoding(scope: MemoryScopeKey): Result<string>;
 
+/**
+ * Which derived artifact a {@link IMemoryStore.reconcile} call repairs.
+ *
+ * @remarks
+ * **The operation names its artifact rather than repairing everything wired**,
+ * and the reasons are structural rather than stylistic: the record and fragment
+ * lanes are independently wirable (so an unnamed repair on a fragment-only store
+ * would have to no-op or guess), their units are incommensurable (one vector per
+ * record vs. N), and their costs differ by orders of magnitude — a measured case
+ * put 68 fragments behind a single 56 KB record. An operation whose cost varies
+ * that much along a dimension it does not name is the accidental-expense shape
+ * `IMemoryStore.list`'s required selection exists to prevent.
+ * @public
+ */
+export declare type DerivedArtifact = 'rank' | 'record-vector' | 'fragment-vector';
+
 /**
  * Converter for an attributed {@link IEdge}.
  * @public
@@ -287,6 +306,29 @@ export declare function edgeTargetKey(target: IEdgeTarget): string;
  */
 export declare const embeddedFragmentConverter: Converter<IEmbeddedFragment>;
 
+/**
+ * The envelope's embedding reference if it carries a usable one, `undefined`
+ * otherwise — **the one place `null`-vs-absent is collapsed.**
+ *
+ * @remarks
+ * {@link IMemoryEnvelope.embeddingRef} is `string | null | undefined`, where
+ * `null` and absent both mean *not embedded* (`null` is the explicit sentinel;
+ * absent is the backwards-compat seam). That makes the obvious presence check
+ * wrong in **both** directions, and both mistakes were shipped before this
+ * accessor existed: `!== undefined` counts a `null` as an embedding that is not
+ * there, and `=== undefined` misses a `null` when looking for one that is
+ * missing. Neither is a type error, and neither is visible to a coverage gate,
+ * because the sentinel is a *value* rather than a branch.
+ *
+ * Returning the reference rather than a boolean is deliberate: a caller that
+ * needs the string gets the check for free, so there is no second, weaker way
+ * to ask.
+ *
+ * **Do not test `embeddingRef` for presence directly — call this.**
+ * @public
+ */
+export declare function embeddingRefOf(envelope: IMemoryEnvelope): string | undefined;
+
 /**
  * Consumer-supplied domain key. The stable entity identity across versions;
  * the package never mints identity. Equals {@link MemoryId} for non-temporal
@@ -394,9 +436,52 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
     /** {@inheritDoc IMemoryStore.getById} */
     getById(scope: MemoryScopeKey, id: MemoryId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
     /** {@inheritDoc IMemoryStore.list} */
-    list(filter?: IMemoryStoreListFilter): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+    list(selection: MemoryListSelection): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+    /** {@inheritDoc IMemoryStore.coverage} */
+    coverage(): Promise<Result<IDerivedStateCoverage>>;
+    /** {@inheritDoc IMemoryStore.listEntries} */
+    listEntries(): Promise<Result<ReadonlyArray<IIndexedMemoryEntry>>>;
     /** {@inheritDoc IMemoryStore.listScoped} */
     listScoped(): Promise<Result<ReadonlyArray<IScopedMemoryRecord>>>;
+    /** {@inheritDoc IMemoryRecordResolver.resolveRecord} */
+    resolveRecord(scope: MemoryScopeKey, id: MemoryId): Result<IMemoryRecord<unknown> | undefined>;
+    private _codec;
+    /** {@inheritDoc IIdentityResolver.resolveIdentity} */
+    resolveIdentity(kind: Kind, entityId: EntityId): Result<IIdentityCodecResult>;
+    /**
+     * Materialize a selected set of entries into records, dropping any that have
+     * vanished since selection.
+     *
+     * @remarks
+     * A miss is not a failure. Selection reads the in-memory index and
+     * materialization reads storage, so a record deleted in between is a legitimate
+     * race and yields a shorter list rather than an error. A read that FAILS is a
+     * real fault and propagates.
+     */
+    private _materialize;
+    /**
+     * Materialize one entry, treating "gone" as a fault rather than a miss.
+     *
+     * @remarks
+     * For paths where a vanished record really does mean the index and the vault
+     * disagree, rather than that something legitimately removed it in between.
+     *
+     * Three of the four callers hold the write lock, so nothing can have removed
+     * the record since the entry was read. `get()`'s versioned path does not, and
+     * is safe only because temporal kinds never physically delete a version — they
+     * invalidate in place, and cap-cull does not apply to them. **If eviction is
+     * ever added to the temporal path, that caller must change**, or it
+     * reintroduces the race this method exists to detect.
+     *
+     * `listScoped` also does not hold the lock, and uses this deliberately anyway:
+     * it feeds a coverage report, so a silent drop there is worse than a loud
+     * failure. See its comment, and `docs/FUTURE.md` for the eviction window.
+     *
+     * The drop-tolerant counterpart is {@link FileTreeMemoryStore._materialize},
+     * for readers where a record that vanished between selection and
+     * materialization is a miss rather than a fault.
+     */
+    private _resolveRequired;
     /** {@inheritDoc IMemoryStore.asRecordSource} */
     asRecordSource(): IMemoryRecordSource;
     /**
@@ -407,8 +492,8 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      * contributes nothing.
      */
     private static _projectAsOf;
-    /** {@inheritDoc IMemoryStore.reconcileRank} */
-    reconcileRank(kind: Kind): Promise<Result<number>>;
+    /** {@inheritDoc IMemoryStore.reconcile} */
+    reconcile(kind: Kind, artifact: DerivedArtifact): Promise<Result<ReconcileReport>>;
     /** {@inheritDoc IMemoryStore.put} */
     put(record: IMemoryRecord<unknown>): Promise<Result<IMemoryRecord<unknown>>>;
     /** {@inheritDoc IMemoryStore.delete} */
@@ -584,7 +669,7 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
     private _isMutableMetadataUnchanged;
     private _contentHash;
     /**
-     * The locked body of {@link FileTreeMemoryStore.reconcileRank}.
+     * The rank branch of {@link FileTreeMemoryStore.reconcile}, under the write lock.
      *
      * @remarks
      * Re-reads each record's file rather than trusting the in-memory index, for
@@ -613,13 +698,15 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      * another on a reconcile. `_stampRank` itself is reused verbatim, which also
      * inherits its throw semantics (logged at `warn`, `rank` cleared).
      */
+    private _reconcileLocked;
+    /** The rank branch of {@link FileTreeMemoryStore._reconcileLocked}. */
     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;
+    private _rewriteEnvelope;
     /**
      * Stamp the store-computed {@link IMemoryEnvelope.rank} onto a fully-built,
      * fully-stamped record by running the kind's registered {@link RankProjector}.
@@ -633,7 +720,6 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      * than preserving it), so a ranking bug never loses an authoritative write.
      */
     private _stampRank;
-    private _codecFor;
     private _policyFor;
     /** {@inheritDoc IMemoryStore.dedupScopeFor} */
     dedupScopeFor(kind: Kind): DedupScope;
@@ -693,6 +779,28 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
     private _loadRecordFile;
 }
 
+/**
+ * The message returned when exactly one of `entityId` / `kind` is supplied.
+ *
+ * @remarks
+ * They travel together because `kind` is what selects the identity codec, and the
+ * codec is what makes the resolution unambiguous. One without the other is not a
+ * partial narrowing that could be honored best-effort — it is not a narrowing at all.
+ * @public
+ */
+export declare const FRAGMENT_NARROWING_INCOMPLETE_MESSAGE: string;
+
+/**
+ * The loud-degradation message returned when a query carries a record narrowing but
+ * no {@link IIdentityResolver} is wired to resolve it.
+ *
+ * @remarks
+ * Deliberately a `Failure` rather than a silently-global search: answering a scoped
+ * question with an unscoped result is the failure this narrowing exists to remove.
+ * @public
+ */
+export declare const FRAGMENT_NARROWING_UNRESOLVABLE_MESSAGE: string;
+
 /**
  * The loud-degradation message a {@link FragmentSemanticRetriever} returns when a
  * fragment query is issued but no {@link IFragmentSemanticBackend | backend} is
@@ -745,18 +853,44 @@ export declare const fragmentLocatorConverter: Converter<IFragmentLocator>;
  */
 export declare class FragmentSemanticRetriever {
     private readonly _backend;
+    private readonly _identityResolver;
     private constructor();
     /** What this retriever can do given its wiring. */
     get capabilities(): IFragmentRetrieverCapabilities;
-    /** Family-convention factory. */
+    /**
+     * Family-convention factory.
+     *
+     * @param params - `backend` wires fragment recall itself. `identityResolver`
+     * resolves a query's `(kind, entityId)` narrowing to a storage address;
+     * `IMemoryStore` implements it, so the usual wiring is
+     * `{ backend, identityResolver: store }`. It is optional because an unscoped
+     * fragment search needs nothing to resolve — but a query that *does* carry a
+     * narrowing fails loudly without it rather than quietly searching everything.
+     */
     static create(params: {
         readonly backend?: IFragmentSemanticBackend;
+        readonly identityResolver?: IIdentityResolver;
     }): Result<FragmentSemanticRetriever>;
     /**
      * Embed `query.semantic`, query the fragment index, and return the per-fragment
      * hits in descending score order. Fails loudly when no backend is wired.
      */
     retrieve(query: IFragmentQuery): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    /**
+     * Turn the query's consumer-facing narrowing into the storage-address narrowing
+     * the index understands.
+     *
+     * @remarks
+     * `kind` selects the identity codec and the codec computes the record's storage
+     * address, so this is a deterministic resolution rather than a search —
+     * which is what makes a colliding `entityId` across kinds a non-issue.
+     *
+     * A **versioned** kind resolves to the entity's own subtree scope and deliberately
+     * carries no `id`, so the narrowing covers every version of the entity — including
+     * superseded ones, which are invalidated but never pruned from the index. A
+     * non-versioned kind resolves to exactly one record.
+     */
+    private _resolveOptions;
     /**
      * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`
      * and a thrown/rejected promise into a single `fragment recall: <label> failed`
@@ -788,11 +922,12 @@ export declare function guardRetrieverCapabilities(query: IMemoryQuery, capabili
  */
 export declare class HistoryRetriever implements IMemoryRetriever {
     private readonly _index;
+    private readonly _resolver;
     private constructor();
     /** {@inheritDoc IMemoryRetriever.capabilities} */
     get capabilities(): IMemoryRetrieverCapabilities;
     /** Family-convention factory. */
-    static create(index: IMemoryIndex): Result<HistoryRetriever>;
+    static create(params: IRetrieverCreateParams): Result<HistoryRetriever>;
     /** {@inheritDoc IMemoryRetriever.retrieve} */
     retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
     /** A version's world-truth start: its `valid_at`, defaulting to `created` when absent. */
@@ -855,6 +990,31 @@ export declare class HybridRetriever implements IMemoryRetriever {
     private _projectQuery;
 }
 
+/**
+ * How much of one derived artifact exists, for one {@link Kind}.
+ *
+ * @remarks
+ * Two numbers rather than a percentage, deliberately: a ratio cannot express
+ * *"nothing was expected"*, and a kind that is intentionally not derived (an
+ * excluded kind, a kind with no projector) is a normal and healthy state that a
+ * `0%` would render as an alarm.
+ * @public
+ */
+export declare interface IArtifactCoverage {
+    /**
+     * Records of this kind the store would derive this artifact for, **after** any
+     * exclusion. Read against {@link IDerivedStateCoverage.records} for the same
+     * kind: `records: 40, expected: 0` is the exclusion story, stated rather than
+     * inferred.
+     */
+    readonly expected: number;
+    /**
+     * Of those, how many the **store believes** are covered. See
+     * {@link IIndexCoverage.indexSize} for why the word "believes" is load-bearing.
+     */
+    readonly covered: number;
+}
+
 /**
  * Registry of per-kind body Converters. Each memory {@link Kind} registers the
  * validated shape of its body; the store dispatches an `unknown` body through
@@ -998,6 +1158,35 @@ export declare interface ICycleGuardEdge {
     readonly type: LinkType;
 }
 
+/**
+ * A snapshot of how much of the store's **derived state** exists, resolved by
+ * {@link Kind} — the answer to *"is my derived state consistent with my
+ * records?"*.
+ *
+ * @remarks
+ * **Absent is not zero.** Each artifact member is optional, and `undefined` means
+ * *this artifact is not derived here at all* — no rank projector is registered,
+ * or that index lane is not wired. It never means *nothing is covered*. Folding
+ * the two would make a health surface render a confident `0%` for a feature the
+ * deployment deliberately did not turn on, which is the same defect as
+ * `embeddingRef`'s three-way ambiguity one level up.
+ *
+ * So: `fragmentVectors: undefined` is a store with no fragment index and is not a
+ * problem. `fragmentVectors: { indexRecordCount: 0, indexFragmentCount: 0 }` is a
+ * wired fragment index holding nothing, and probably is.
+ * @public
+ */
+export declare interface IDerivedStateCoverage {
+    /** Records per kind — the denominator every other number is read against. */
+    readonly records: ReadonlyMap<Kind, number>;
+    /** Absent when no kind has a registered {@link RankProjector}. */
+    readonly rank?: ReadonlyMap<Kind, IArtifactCoverage>;
+    /** Absent when the record-vector lane is not wired. */
+    readonly recordVectors?: IIndexCoverage;
+    /** Absent when the fragment lane is not wired. */
+    readonly fragmentVectors?: IFragmentIndexCoverage;
+}
+
 /**
  * An attributed link between two records. Carries the relation type, the
  * scope-qualified {@link IEdgeTarget | target}, and optional confidence /
@@ -1121,6 +1310,27 @@ export declare interface IEntityResolver {
     resolve(candidate: ICandidateRecord, similar: ReadonlyArray<IEntityResolutionCandidate>): Promise<Result<ResolutionVerdict>>;
 }
 
+/**
+ * The minimum a temporal helper needs: something carrying an envelope.
+ *
+ * @remarks
+ * Every predicate and selector in this module reads `envelope.temporal`,
+ * `envelope.created` and `envelope.seq` and **nothing else** — no body has ever
+ * been consulted. Taking the structural shape rather than `IMemoryRecord` lets
+ * the same helpers serve both an `IMemoryRecord<unknown>` (which satisfies it)
+ * and an `IIndexedMemoryEntry` from the index's projected read surface, so the
+ * temporal `asOf` projection can run over envelopes and materialize only the
+ * versions that survive it.
+ *
+ * The selectors are generic in this shape so they return exactly what they were
+ * given rather than widening to the constraint.
+ * @public
+ */
+export declare interface IEnvelopeCarrier {
+    /** The envelope the temporal predicates read. */
+    readonly envelope: IMemoryEnvelope;
+}
+
 /**
  * Stage 3 — the host's fact extractor. Turns a classified item into zero or more
  * {@link ICandidateRecord}s. Each candidate's body is validated against the
@@ -1328,6 +1538,31 @@ export declare interface IFileTreeMemoryStoreCreateParams {
     readonly onRecordError?: MemoryRecordErrorMode;
 }
 
+/**
+ * Coverage of the fragment-granular vector index.
+ *
+ * @remarks
+ * **Aggregate only, and the reason is structural rather than an omission.** The
+ * record lane has a per-record marker on the envelope (`embeddingRef`), so its
+ * numerator falls out of the same free walk that produces the denominator. The
+ * fragment lane has **no envelope marker at all** — nothing on a record says
+ * whether it has fragments — so a per-kind numerator would cost one
+ * `IFragmentVectorIndex.has` call per record, and coverage is contractually
+ * cheap (see {@link IMemoryStore.coverage}).
+ *
+ * The per-kind **denominator** is still available on
+ * {@link IDerivedStateCoverage.records}. A caller who needs the per-kind
+ * numerator runs `reconcile(kind, 'fragment-vector')`, which reports it because
+ * it is already paying for the walk.
+ * @public
+ */
+export declare interface IFragmentIndexCoverage {
+    /** Records with at least one fragment held. Mirrors `IFragmentVectorIndex.recordCount`. */
+    readonly indexRecordCount: number;
+    /** Total fragments held — the fan-out. Mirrors `IFragmentVectorIndex.fragmentCount`. */
+    readonly indexFragmentCount: number;
+}
+
 /**
  * A half-open `[start, end)` span into a record's body — the in-record locator a
  * {@link IFragmentVectorIndex} may carry on a fragment. `start` is inclusive,
@@ -1373,6 +1608,104 @@ export declare interface IFragmentQuery {
      * Applied during selection (before the `topK` cut). Omit for uncapped.
      */
     readonly maxPerRecord?: number;
+    /**
+     * Narrow the search to one record's fragments: the consumer-supplied domain key
+     * of the record to search within. **Must be supplied with
+     * {@link IFragmentQuery.kind}.**
+     *
+     * @remarks
+     * The narrowing is applied **during selection, before the `topK` cut**, so the
+     * `topK` you ask for is the `topK` you get. Filtering a global result afterwards
+     * is not equivalent: it truncates to `topK` across every record first, so a scoped
+     * search would come back short whenever other records outscored this one's
+     * fragments.
+     *
+     * For a versioned kind this narrows to **every version of the entity** — literally
+     * every version, superseded ones included, because invalidation stamps `invalid_at`
+     * without pruning that version's fragments. Nothing on a hit distinguishes a
+     * current fragment from a historical one. That matches the record-granular vector
+     * lane; it is not currency filtering.
+     */
+    readonly entityId?: EntityId;
+    /**
+     * The kind of the record named by {@link IFragmentQuery.entityId}. **Must be
+     * supplied with it.**
+     *
+     * @remarks
+     * This is not decoration and not a filter: `kind` **selects the identity codec**,
+     * and the codec computes the storage address. An `EntityId` promises no uniqueness
+     * beyond a scope — the same id under two kinds is the ordinary case, not a
+     * pathological one — so without `kind` the resolution is ambiguous, and with it
+     * ambiguity is structurally impossible.
+     */
+    readonly kind?: Kind;
+}
+
+/**
+ * Selection-time narrowing for {@link IFragmentVectorIndex.query}. Every member is
+ * applied **before** the `topK` cut.
+ *
+ * @remarks
+ * `scope` (optionally with `id`) is the record narrowing. It is expressed as a
+ * storage address rather than as a consumer-facing `(kind, entityId)` because that
+ * is what the index is keyed by; resolving one to the other is
+ * `IIdentityResolver.resolveIdentity`'s job, and doing it above the index keeps the
+ * index dealing only in the keys it actually holds.
+ *
+ * **`scope` alone is not a coarser accident — it is what a versioned kind needs.**
+ * `TemporalIdentityCodec` files every version of an entity in its own per-entity
+ * subtree, so for a versioned kind the entity's subtree *is* the narrowing and
+ * `{ scope }` means "every version of this entity". A non-versioned kind resolves to
+ * a single record and supplies `{ scope, id }`.
+ *
+ * **"Every version" is literal, and includes superseded ones.** Invalidation stamps
+ * `invalid_at` on an envelope; it does not prune that version's fragments from the
+ * index. So a scope-narrowed query returns current and historical fragments alike,
+ * and a hit carries nothing that distinguishes them — `IVectorQueryHit` has no
+ * temporal fields. This is the record-granular vector lane's existing behaviour
+ * rather than something this narrowing introduces, but do not read the subtree
+ * narrowing as currency filtering: it is not, and there is no `asOf` axis here to
+ * make it so.
+ * @public
+ */
+export declare interface IFragmentQueryOptions {
+    /**
+     * Maximum number of fragments any single record may contribute. Omit for
+     * uncapped. With a single-record narrowing (`scope` + `id`) this caps the one
+     * record's contribution, which is a second cap on the same axis rather than a
+     * cross-record fairness knob — usually you want one or the other, not both.
+     */
+    readonly maxPerRecord?: number;
+    /**
+     * Restrict the search to fragments of records in this scope. Omit to search every
+     * record.
+     */
+    readonly scope?: MemoryScopeKey;
+    /**
+     * With {@link IFragmentQueryOptions.scope}, restrict further to the single record
+     * at `(scope, id)`. Ignored — and meaningless — without `scope`, since a bare `id`
+     * does not address a record.
+     */
+    readonly id?: MemoryId;
+}
+
+/**
+ * A fragment-vector reconcile.
+ *
+ * @remarks
+ * Note there is no `restamped`: the fragment lane has **no envelope marker**, so
+ * there is no reference that can go missing and nothing to restamp. The
+ * asymmetry with {@link IVectorReconcileReport} is real rather than an oversight.
+ * @public
+ */
+export declare interface IFragmentReconcileReport extends IReconcileReportBase {
+    readonly artifact: 'fragment-vector';
+    /** Records already represented, needing no embedder call. */
+    readonly alreadyIndexed: number;
+    /** Records whose embedder produced no fragments — this lane's decline. */
+    readonly declined: number;
+    /** Fragments written by this call — the fan-out `repaired` cannot express. */
+    readonly fragments: number;
 }
 
 /**
@@ -1433,12 +1766,124 @@ export declare interface IFragmentVectorIndex {
     /**
      * Return the `topK` nearest fragments to `vector`, in descending score order,
      * each hit carrying its record `target` plus whichever of `locator` /
-     * `fragmentId` the stored fragment was added with. When
-     * `maxPerRecord` is supplied, no more than that many fragments of any single
-     * record appear in the result — the cap is applied during selection (before the
-     * `topK` cut) so one long document cannot crowd out others.
+     * `fragmentId` the stored fragment was added with.
+     *
+     * @remarks
+     * **Every member of `options` is applied during selection, before the `topK`
+     * cut.** That ordering is the contract, not an implementation detail: a narrowing
+     * applied afterwards would mean the caller's `topK` is not the `topK` that reached
+     * the index, so a scoped search would be exact only when a global over-fetch
+     * happened to be generous enough. See {@link IFragmentQueryOptions}.
+     */
+    query(vector: Float32Array, topK: number, options?: IFragmentQueryOptions): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    /**
+     * Whether this index holds **any** fragment for the scope-qualified `target`.
+     *
+     * @remarks
+     * The record-granular rationale on {@link IVectorIndex.has} applies verbatim —
+     * a repair that trusts `embeddingRef` is not a repair. Note the granularity
+     * this deliberately does **not** offer: it answers *"is this record
+     * represented?"*, not *"is this particular fragment present?"*. Fragment
+     * writes are whole-record-replace, so a record is either represented by the
+     * current fragment set or not represented at all; a per-fragment membership
+     * check would imply an incremental write path that does not exist.
+     */
+    has(target: IEdgeTarget): Promise<Result<boolean>>;
+    /**
+     * The number of **records** with at least one fragment held.
+     *
+     * @remarks
+     * Deliberately **not** named `size`, unlike {@link IVectorIndex.size}. This
+     * index is one-to-many, so `size` has two defensible readings and a reader
+     * arriving from the record-granular sibling — where `size` counts vectors —
+     * would take the wrong one silently. Two explicitly-named counts cost one extra
+     * member and cannot be misread.
+     */
+    readonly recordCount: number;
+    /**
+     * The total number of **fragments** held across all records.
+     *
+     * @remarks
+     * The fan-out, and the number a caller actually watches: fragments-per-record
+     * is what makes a fragment reconcile expensive, and neither `recordCount` nor a
+     * record-granular count answers it.
      */
-    query(vector: Float32Array, topK: number, maxPerRecord?: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    readonly fragmentCount: number;
+    /**
+     * Re-embed every record from `source` and rebuild the fragment index from
+     * scratch — the **backfill / reconcile** operation, sibling to
+     * {@link IVectorIndex.rebuild}.
+     *
+     * @remarks
+     * On the contract for exactly the reasons its record-granular sibling is, and
+     * the fragment lane was worse off: `rebuild` existed only on the bundled
+     * in-memory class, and the durable `SqliteVecFragmentIndex` had **no backfill
+     * at all**, so a persistent fragment index could not be reconciled by any
+     * route — contractual or concrete. Records written while it was unwired, a
+     * re-embed after a segmenter change, and reconciliation after a swallowed
+     * fragment-embed failure were all unreachable.
+     *
+     * Semantics are kept observably identical to the record-granular sibling so a
+     * caller who has learned one has learned both: a `source.list()` failure is
+     * fatal and carries no detail (nothing was attempted, and the existing index is
+     * untouched); a genuine rebuild then resets first; `onRecordError` defaults to
+     * `'fail'`; and a failure carries whatever the attempt had established on the
+     * `detail`.
+     *
+     * **A rebuild does NOT re-establish the vector dimension on a persistent
+     * index, and this is the one place the two shipped implementations genuinely
+     * differ.** The in-memory indexes forget their dimension when they reset, so a
+     * rebuild with a different-dimension embedder simply re-establishes it. A
+     * `vec0`-backed index cannot: its reset is a `DELETE FROM`, the table's
+     * declared dimension is part of its schema, and `vec0` has no `ALTER TABLE`.
+     * So a rebuild that changes dimension **succeeds in memory and fails on
+     * SQLite**, where it needs the same drop-and-re-index the package README
+     * prescribes for any schema change (drop the table, or point the index at a
+     * fresh `tableName`). Only embedding time is at risk — vectors are derived and
+     * the vault records remain authoritative.
+     */
+    rebuild(source: IMemoryRecordSource, embed: FragmentEmbedder, options?: IVectorRebuildOptions): Promise<DetailedResult<IFragmentVectorRebuildReport, IFragmentVectorRebuildReport>>;
+}
+
+/**
+ * What an {@link IFragmentVectorIndex.rebuild} established, resolved by
+ * {@link Kind} — the fragment-granular sibling of {@link IVectorRebuildReport}.
+ *
+ * @remarks
+ * The rule stated on {@link IVectorRebuildReport} applies here verbatim and is
+ * not re-opened: **every count is resolved by kind unless there is a stated
+ * reason it cannot be**, `excluded` is optional because only the source can know
+ * it, and the report is carried on a failure as well as a success.
+ *
+ * The one member with no record-granular analogue is
+ * {@link IFragmentVectorRebuildReport.fragments | fragments} — the fan-out. It is
+ * the number that distinguishes this lane: `indexed: 40` says forty records are
+ * represented and says nothing about whether that cost forty embedding round
+ * trips or four thousand, which is the difference between a reconcile that
+ * finishes in a second and one that blocks a request past thirty.
+ *
+ * A **declined** record is one whose {@link FragmentEmbedder} returned an empty
+ * array — the fragment lane's way of saying *intentionally not embedded*. Note
+ * this is a different mechanism from a {@link MemoryEmbedder} decline: an empty
+ * array still performs a real whole-record-replace (which is what clears any
+ * stale fragments), where a record-granular decline skips the index entirely.
+ * @public
+ */
+export declare interface IFragmentVectorRebuildReport {
+    /** Records that ended with at least one fragment held, per kind. */
+    readonly indexed: ReadonlyMap<Kind, number>;
+    /** Fragments held, per kind — the fan-out `indexed` cannot express. */
+    readonly fragments: ReadonlyMap<Kind, number>;
+    /** Records whose embedder intentionally produced no fragments, per kind. */
+    readonly declined: ReadonlyMap<Kind, number>;
+    /**
+     * Records the source filtered out before the rebuild saw them, per kind.
+     * `undefined` means *this source does not report exclusions*; an empty map
+     * means *it does, and excluded nothing*.
+     */
+    readonly excluded?: ReadonlyMap<Kind, number>;
+    /** Records that failed, per record, with the error — a fault, never a decline. */
+    readonly skipped: ReadonlyArray<ISkippedVectorRecord>;
 }
 
 /**
@@ -1482,6 +1927,97 @@ export declare interface IIdentityCodecResult {
     readonly isVersioned: boolean;
 }
 
+/**
+ * Resolves a consumer-facing `(kind, entityId)` address to the storage address the
+ * vault files it under, **without reading the record**.
+ *
+ * @remarks
+ * This is the resolution `IMemoryStore.get(kind, entityId)` already performs before
+ * it reads anything: `kind` selects the kind's `IIdentityCodec`, and the codec's
+ * `encode` computes `{ scope, idStem, isVersioned }`. Exposing it separately lets a
+ * caller that needs only the *address* — a fragment query narrowing to one record,
+ * say — avoid paying for a read it does not want.
+ *
+ * **The resolution is a function, not a search, and that is the load-bearing
+ * property.** A consumer holds an `EntityId`; a vector hit is addressed by a
+ * `(scope, id)` pair; and `EntityId` promises no uniqueness beyond a scope, so the
+ * same id may legitimately appear in several scopes (a document `acme-corp` under
+ * one kind and the entity `acme-corp` under another is the ordinary case, not a
+ * pathological one). Supplying `kind` selects one codec, and a codec cannot return
+ * two answers — so ambiguity is structurally impossible rather than merely unlikely,
+ * and no disambiguation pass is needed anywhere downstream.
+ *
+ * Narrow by design, mirroring `IMemoryRecordResolver`: a component that needs to
+ * turn an entity address into a storage address should depend on this rather than on
+ * the whole store.
+ * @public
+ */
+export declare interface IIdentityResolver {
+    /**
+     * The storage address `(kind, entityId)` maps to, without reading the record.
+     *
+     * @param kind - Selects the identity codec. Required: it is what makes the
+     * resolution unambiguous.
+     * @param entityId - The consumer-supplied domain key.
+     * @returns `Success` with the codec's `{ scope, idStem, isVersioned }`, or
+     * `Failure` if no codec is registered for `kind` (and no default is wired) or the
+     * codec rejects the id. Both are caller errors and both are loud.
+     */
+    resolveIdentity(kind: Kind, entityId: EntityId): Result<IIdentityCodecResult>;
+}
+
+/**
+ * Coverage of the record-granular vector index.
+ * @public
+ */
+export declare interface IIndexCoverage {
+    /** Per-kind expected/covered, derived from the envelope walk. */
+    readonly perKind: ReadonlyMap<Kind, IArtifactCoverage>;
+    /**
+     * What the index **actually holds**, whole-index.
+     *
+     * @remarks
+     * **This is a fact and {@link IArtifactCoverage.covered} is a belief, and the
+     * two are reported separately because their disagreement is the only free
+     * signal that distinguishes a persistent index from a fresh one.** `covered`
+     * counts envelopes carrying an `embeddingRef`; `indexSize` counts vectors. With
+     * a persistent index they agree. With an in-memory index at open they do not —
+     * the envelopes still claim references from previous sessions while the index
+     * holds nothing, so `covered` **lies, in the confident direction**.
+     *
+     * Collapsing them into one "coverage %" would destroy that signal, which is why
+     * this type does not offer one.
+     */
+    readonly indexSize: number;
+}
+
+/**
+ * What the index HOLDS and what every index read returns: a record's scope and
+ * its {@link IMemoryEnvelope}, and **no body**.
+ *
+ * @remarks
+ * The index is a derived *selection* structure, and selection has never needed a
+ * body — every filter the store and the retrievers apply reads envelope fields
+ * (`scope` / `kind` / `tags` / `contentHash` / `provenance` / `links` /
+ * `temporal` / `updated` / `seq` / `rank`). Returning whole records made every
+ * conforming index hold every body by construction, which was the store's
+ * resident-memory ceiling; returning envelopes removes it from the contract
+ * rather than from one implementation.
+ *
+ * A caller that needs the body **materializes it explicitly** — through
+ * {@link IMemoryStore.getById}, or an `IMemoryRecordResolver` where one is
+ * wired. That is deliberately visible: a lazy `body` getter would have kept
+ * every call site compiling while turning a memory read into a file read behind
+ * an unchanged type, which is a silent performance cliff rather than a migration.
+ * @public
+ */
+export declare interface IIndexedMemoryEntry {
+    /** The scope the record is stored under. */
+    readonly scope: MemoryScopeKey;
+    /** The record's envelope. No body — see the remarks. */
+    readonly envelope: IMemoryEnvelope;
+}
+
 /**
  * A memory record paired with the {@link MemoryScopeKey | scope} it lives
  * under. The scope is not carried on the {@link IMemoryEnvelope} (it is derived
@@ -1689,7 +2225,7 @@ export declare interface IMemoryEnvelope {
      * 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
+     * `IMemoryStore.reconcile(kind, 'rank')` after registering a projector against a
      * populated store.
      */
     readonly rank?: number;
@@ -1723,40 +2259,98 @@ export declare interface IMemoryFileParts {
  * patched incrementally on every write ({@link IMemoryIndex.patch}).
  *
  * @remarks
- * B1 builds the maps; link-traversal BFS over {@link IMemoryIndex.backlinks}
- * is B2. The accessors return records (not bare ids) so the B2 retrievers can
- * consume them directly.
+ * Every read returns the projected {@link IIndexedMemoryEntry} — scope and
+ * envelope, no body. See that type for why.
+ *
+ * **The conformance rule: an index is a derived, COMPLETE, FAITHFUL projection
+ * of the vault.** An implementation may change *where* entries are stored and
+ * *how* they are looked up; it may not change *which* entries exist or *what any
+ * envelope says*. Concretely, {@link IMemoryIndex.entries} must return exactly
+ * one entry per record the store has written and not deleted, and each entry's
+ * envelope must be the one the store patched in.
+ *
+ * An index that filters, truncates, deduplicates, or synthesizes entries is not
+ * a conforming implementation, and the reason is not tidiness: **the store's
+ * write path derives from these reads** — content-hash dedup, write-policy
+ * admission cohorts, and temporal version histories all read the index. An index
+ * that hides an entry does not merely hide it from queries; it changes what the
+ * next write does. That is why the previous guidance said only a faithful
+ * delegating decorator was safe to inject. This invariant is what that guidance
+ * was reaching for, stated so that a genuinely different implementation (a
+ * SQLite-backed index, a lazily-paged one) is permitted while the reshaping that
+ * was the actual hazard stays out.
+ *
+ * **Ordering is NOT part of the contract.** {@link IMemoryIndex.entries} may
+ * return entries in any order and callers that need one sort explicitly. Note
+ * this is a *behavioural* freedom the compiler cannot police: the bundled
+ * {@link MemoryIndex} iterates a `Map` and so returns insertion order, which is
+ * stable and observable, so code that came to rely on it keeps compiling and
+ * changes results. The ordered accessors ({@link IMemoryIndex.byRecency},
+ * {@link IMemoryIndex.byRank}, and the recency-ordered `byKind` / `byTag`) are
+ * the supported way to ask for an order.
  * @public
  */
 export declare interface IMemoryIndex {
     /**
-     * Replace the entire index from a full set of records (a store walk).
-     * @returns The number of records indexed.
+     * Replace the entire index from a full set of entries (a store walk).
+     *
+     * @remarks
+     * Takes the **projected** {@link IIndexedMemoryEntry} form, not whole records,
+     * and the distinction is load-bearing rather than cosmetic: **`patch` writes,
+     * `rebuild` reads.** A rebuild is a whole-vault read that happens to terminate
+     * in the index, so requiring whole records here would force every caller — the
+     * store's own open path included — to materialize N bodies purely to feed a
+     * structure that projects the envelope back out and discards them. `patch`
+     * keeps whole records because it carries exactly one, which its caller already
+     * holds.
+     *
+     * @returns The number of entries indexed.
      */
-    rebuild(entries: ReadonlyArray<IIndexedMemoryRecord>): Result<number>;
+    rebuild(entries: ReadonlyArray<IIndexedMemoryEntry>): Result<number>;
     /**
      * Apply a single incremental change. `'put'` inserts or replaces the entry
      * at its `(scope, id)` key (removing any prior associations first); `'delete'`
      * removes it.
+     *
+     * @remarks
+     * Takes the whole record — see {@link IMemoryIndex.rebuild} for why this one
+     * does and that one does not. It costs nothing (the caller is mid-write and
+     * holds the record already) and it is the single point at which an index
+     * maintaining a body-derived view could observe content without a re-read.
+     * What is *held* is still only the projection.
+     *
      * @returns The entry that was applied.
      */
     patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord>;
-    /** Every indexed entry (scope + record). Primary read surface for the store. */
-    entries(): ReadonlyArray<IIndexedMemoryRecord>;
-    /** Records of the given kind, in recency order (most-recently-updated first). */
-    byKind(kind: Kind): ReadonlyArray<IMemoryRecord<unknown>>;
-    /** Records carrying the given tag, in recency order. */
-    byTag(tag: Tag): ReadonlyArray<IMemoryRecord<unknown>>;
-    /** All records in recency order (most-recently-updated first). */
-    byRecency(): ReadonlyArray<IMemoryRecord<unknown>>;
-    /**
-     * All records ordered by store-computed {@link IMemoryEnvelope.rank} descending,
-     * with recency (most-recently-updated, then `seq`) as a tiebreak. Records with
-     * an absent `rank` sort LAST (after every ranked record), then by recency among
+    /** Every indexed entry (scope + envelope). Primary read surface for the store. */
+    entries(): ReadonlyArray<IIndexedMemoryEntry>;
+    /**
+     * The entry at a scope-qualified address, or `undefined` if none.
+     *
+     * @remarks
+     * On the contract because its absence made every caller that wanted **one**
+     * entry rebuild a map of **all** of them: both `SemanticRetriever` (resolving
+     * at most `topK` hits) and `LinkTraversalRetriever` (resolving a BFS frontier)
+     * built a full-index `Map` per query for want of this. The index already keys
+     * on `(scope, id)` internally, so this exposes a lookup it was doing anyway.
+     */
+    get(target: IEdgeTarget): IIndexedMemoryEntry | undefined;
+    /** Entries of the given kind, in recency order (most-recently-updated first). */
+    byKind(kind: Kind): ReadonlyArray<IIndexedMemoryEntry>;
+    /** Entries carrying the given tag, in recency order. */
+    byTag(tag: Tag): ReadonlyArray<IIndexedMemoryEntry>;
+    /** All entries in recency order (most-recently-updated first). */
+    byRecency(): ReadonlyArray<IIndexedMemoryEntry>;
+    /**
+     * All entries ordered by store-computed {@link IMemoryEnvelope.rank} descending,
+     * with recency (most-recently-updated, then `seq`) as a tiebreak. Entries with
+     * an absent `rank` sort LAST (after every ranked entry), then by recency among
      * themselves. Serves a bounded top-M ({@link IMemoryEnvelope.rank}-ordered) page
-     * from the in-memory index with no full-vault (filesystem) scan.
+     * from the in-memory index with no full-vault (filesystem) scan — and since the
+     * page is envelope-only, a caller taking the top M materializes M bodies rather
+     * than the vault.
      */
-    byRank(): ReadonlyArray<IMemoryRecord<unknown>>;
+    byRank(): ReadonlyArray<IIndexedMemoryEntry>;
     /**
      * The scope-qualified sources of records whose `links` point AT `target`
      * (inbound edges), keyed on the target's `(scope, id)` address. The seed map
@@ -2058,6 +2652,72 @@ export declare interface IMemoryRecord<TBody = unknown> {
     readonly body: TBody;
 }
 
+/**
+ * What a {@link IMemoryRecordSource.list} call yields: the records the rebuild
+ * should embed, plus — when the source can say — what it filtered out on the way.
+ *
+ * @remarks
+ * The exclusion count originates here because **this is the layer where the
+ * decision is made**. A rebuild never sees an excluded record, so it cannot count
+ * one; a report assembled without this would silently undercount coverage, and
+ * undercount in the direction of looking healthier.
+ *
+ * A store accessor answering "how many are excluded right now" was considered and
+ * declined: it answers a *different question* than the report does — "excluded
+ * right now" versus "excluded in this reconcile" — and the two legitimately differ
+ * whenever records are written between reconciles. Two correct-and-unequal numbers
+ * are worse than one absent number: they invite treating a real difference as a
+ * bug, or picking whichever supports the conclusion already held.
+ * @public
+ */
+export declare interface IMemoryRecordListing {
+    /** Every record the rebuild should embed, each paired with its scoped address. */
+    readonly records: ReadonlyArray<IScopedMemoryRecord>;
+    /**
+     * Records this source filtered out, counted by {@link Kind}. Omit it entirely if
+     * the source does not track exclusions — that reads as *"cannot say"* on
+     * {@link IVectorRebuildReport.excluded}, which is distinct from an empty map
+     * (*"nothing was excluded"*).
+     */
+    readonly excluded?: ReadonlyMap<Kind, number>;
+}
+
+/**
+ * Materializes one record's body from its scope-qualified address — the other
+ * half of the partial-read split, and the narrowest seam that can be.
+ *
+ * @remarks
+ * The index holds `IIndexedMemoryEntry` (scope + envelope, no body), so anything
+ * that *selects* works from envelopes and anything that must *return records*
+ * resolves the survivors through this. `FileTreeMemoryStore` implements it over
+ * the same read path `getById` uses, so a resolved record is byte-identical to a
+ * keyed read, verification included.
+ *
+ * **Deliberately one method, and deliberately not the store.** A retriever needs
+ * exactly this capability; handing it an `IMemoryStore` would hand it `put` and
+ * `delete` as well, and would invert the construction direction (the store builds
+ * retrievers today, not the reverse). One method also keeps a test double
+ * trivial.
+ *
+ * Synchronous `Result` rather than `Promise<Result>` because every shipped
+ * `FileTree` backend resolves without awaiting, and an async signature here would
+ * have rippled through retrievers that are otherwise synchronous over the index.
+ * A future backend that genuinely needs I/O should be adapted at its own boundary
+ * rather than by making this contract async for everyone.
+ *
+ * Resolving an address the vault does not hold is `succeed(undefined)`, not a
+ * failure — an entry can legitimately vanish between selection and
+ * materialization (a concurrent delete), and that is a miss rather than a fault.
+ * A failure means the record is there and could not be read.
+ * @public
+ */
+export declare interface IMemoryRecordResolver {
+    /**
+     * The record at `(scope, id)`, or `undefined` if the vault does not hold one.
+     */
+    resolveRecord(scope: MemoryScopeKey, id: MemoryId): Result<IMemoryRecord<unknown> | undefined>;
+}
+
 /**
  * The minimal record-source surface {@link InMemoryCosineIndex.rebuild} reads to
  * re-embed an entire vault. Each entry carries the record's scope-qualified
@@ -2069,8 +2729,12 @@ export declare interface IMemoryRecord<TBody = unknown> {
  * @public
  */
 export declare interface IMemoryRecordSource {
-    /** List every record in the vault, each paired with its scoped address. */
-    list(): Promise<Result<ReadonlyArray<IScopedMemoryRecord>>>;
+    /**
+     * List every record the rebuild should embed, each paired with its scoped
+     * address, plus the exclusions this source applied if it tracks them. See
+     * {@link IMemoryRecordListing}.
+     */
+    list(): Promise<Result<IMemoryRecordListing>>;
 }
 
 /**
@@ -2108,15 +2772,23 @@ export declare interface IMemoryRetrieverCapabilities {
 
 /**
  * The writable, FileTree-backed, content-hash-deduped memory store.
+ *
+ * @remarks
+ * Extends {@link IMemoryRecordResolver} because the retrievers take a resolver
+ * and a store is the obvious one to hand them — `{ index, resolver: store }` is
+ * the documented wiring, and it has to type-check for the `IMemoryStore` handle
+ * a consumer actually holds, not only for the concrete `FileTreeMemoryStore`.
  * @public
  */
-export declare interface IMemoryStore {
+export declare interface IMemoryStore extends IMemoryRecordResolver, IIdentityResolver {
     /**
      * Keyed read by entity id. Resolves `entityId` to a storage address via the
      * registered {@link IIdentityCodec} for `kind`. Returns `undefined` when no
-     * record exists. For a versioned (temporal) kind this returns the current
-     * version, resolved from the derived in-memory index (not re-read/re-verified
-     * from disk per call — the index is kept in sync with every write).
+     * record exists. For a versioned (temporal) kind the current version is
+     * *selected* from the derived in-memory index — the version history is walked
+     * over envelopes, never bodies — and then that one version is read from
+     * storage. So the selection costs no file reads and the result costs exactly
+     * one, rather than one per version.
      */
     get(kind: Kind, entityId: EntityId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
     /**
@@ -2124,9 +2796,77 @@ export declare interface IMemoryStore {
      */
     getById(scope: MemoryScopeKey, id: MemoryId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
     /**
-     * List records, filtered in-memory over the derived index.
+     * List records: select over the derived index, then materialize the survivors.
+     *
+     * @remarks
+     * **The selection is required and must narrow.** Since the index holds
+     * envelopes only, every returned record is read from storage — so a call that
+     * narrows nothing reads the whole vault, and that has to be a decision rather
+     * than a default. Omitting the argument is a compile error; passing one with no
+     * `scope` / `kind` / `tag` fails with a message naming {@link scanEveryRecord},
+     * which is how a caller says it meant it.
+     *
+     * The requirement buys **explicitness, not a cost bound** — `{ kind }` on a
+     * vault dominated by that kind still materializes most of it. What it prevents
+     * is the whole-vault read nobody chose.
+     *
+     * If you only need to select, use {@link IMemoryStore.listEntries} instead: no
+     * selection, no file reads.
+     */
+    list(selection: MemoryListSelection): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+    /**
+     * How much of the store's **derived state** exists, resolved by {@link Kind}.
+     *
+     * @remarks
+     * Answers *"is my derived state consistent with my records, and if not by how
+     * much?"* for every artifact the store derives — `rank`, record vectors, and
+     * fragment vectors — in one call.
+     *
+     * **Cheap and total, by contract rather than by implementation.** Every input is
+     * an envelope field or an index-side count: it reads **no record bodies** and
+     * calls **no embedder**, and the walk over the vault's own state touches the
+     * filesystem not at all. That is why it takes no selection, unlike
+     * {@link IMemoryStore.list} — the guard there exists because an unnarrowed list
+     * reads the vault, and putting one here would decorate a free operation and make
+     * that guard mean less.
+     *
+     * **The index-side counts are the one exception, and it is the caller's own
+     * index that spends it.** A persistent index answers `size` / `recordCount` /
+     * `fragmentCount` with a query — `SqliteVecVectorIndex` runs a prepared `COUNT`
+     * — so on a durable backend this call does I/O and can **fail**. It is bounded
+     * (one count per wired index, never per record) and it is why the return is a
+     * `Result` rather than a bare value.
+     *
+     * *If a future addition to the report would require reading a record body, it
+     * does not belong on this report.*
+     *
+     * The counterpart is {@link IMemoryStore.reconcile}: coverage says **how big**
+     * the gap is, cheaply; reconcile says **what it was** and closes what it can, at
+     * the cost of re-running the embedder. Neither substitutes for the other.
+     *
+     * **A lane is reported here whenever its *index* is wired**, which is weaker
+     * than what reconcile requires (index **and** embedder). That is intended: an
+     * index without an embedder still holds vectors and still answers queries, so
+     * its coverage is a real number worth reporting. The consequence to expect is a
+     * half-wired store that reports a gap `reconcile` will refuse to close, naming
+     * the missing embedder.
+     */
+    coverage(): Promise<Result<IDerivedStateCoverage>>;
+    /**
+     * Every entry in the vault — scope and envelope, **no bodies**. Reads no files
+     * and requires no selection, because there is nothing to be careful about: it
+     * returns what the index already holds.
+     *
+     * @remarks
+     * This is the whole-vault read most callers actually want. Selection, grouping,
+     * counting, "which kinds are in here", "what links at this" — all of it is
+     * envelope work. Reach for {@link IMemoryStore.list} with
+     * {@link scanEveryRecord} only when you genuinely need every body.
+     *
+     * Synchronous in spirit but `Promise`-returning for consistency with the rest
+     * of the store surface.
      */
-    list(filter?: IMemoryStoreListFilter): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+    listEntries(): Promise<Result<ReadonlyArray<IIndexedMemoryEntry>>>;
     /**
      * List EVERY record in the vault, each paired with its scope-qualified
      * `(scope, id)` address — the projection {@link IMemoryRecordSource} requires.
@@ -2148,6 +2888,11 @@ export declare interface IMemoryStore {
      * every kind participates and the filter is the identity. `listScoped` itself is
      * **not** filtered and remains the whole-vault surface.
      *
+     * The filter also **counts what it drops**, onto
+     * {@link IMemoryRecordListing.excluded} — this is the layer where the exclusion
+     * decision is made and so the only one that can. The count is always present
+     * (empty when nothing was excluded).
+     *
      * 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.
@@ -2209,35 +2954,42 @@ export declare interface IMemoryStore {
      */
     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.
+     * Repair one derived artifact for one {@link Kind} — **targeted and
+     * non-destructive**, unlike `IVectorIndex.rebuild`, which resets the index and
+     * re-embeds everything.
      *
      * @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.
+     * The counterpart to {@link IMemoryStore.coverage}: coverage says **how big**
+     * the gap is and costs nothing; reconcile says **what it was** and closes what
+     * it can, at the cost of reading bodies and re-running the embedder. Neither
+     * substitutes for the other — in particular, only reconcile can distinguish a
+     * *declined* record from a *failed* one, because learning that requires calling
+     * the embedder again.
      *
-     * 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.
+     * **It only touches what is missing.** For the vector lanes it asks
+     * `has(target)` per record and skips the ones already held, so a repair after a
+     * brief outage costs a handful of embedder calls rather than a whole vault.
+     * That check is also the only way to see a record whose vector the index holds
+     * but whose envelope lost its `embeddingRef` — which needs a restamp and no
+     * embedder call at all, and which an `embeddingRef`-only repair cannot detect.
      *
-     * Fails loudly if `kind` has no registered projector: asking to reconcile a
-     * kind you never configured is a caller error, not a no-op.
+     * **`artifact` is required and names one lane.** See {@link DerivedArtifact}
+     * for why an operation repairing "everything wired" would be the wrong shape.
      *
-     * **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.
+     * **A vector lane must be wired on BOTH halves — index *and* embedder — or this
+     * fails, and it is deliberately stricter than {@link IMemoryStore.coverage}.**
+     * The two ask different questions of the same wiring. Coverage asks *what does
+     * the index hold*, which an index alone can answer: an index wired without an
+     * embedder is a legal store (queries work; writes simply do not embed), so
+     * coverage reports that lane rather than pretending it is absent. Reconcile
+     * asks to *produce* vectors, which needs the embedder. So a half-wired store
+     * legitimately reports a coverage gap it cannot repair, and reconcile names the
+     * missing half rather than returning a cheerful success with every record in
+     * `failed`.
+     *
+     * Runs under the store's write lock, like any other mutation.
      */
-    reconcileRank(kind: Kind): Promise<Result<number>>;
+    reconcile(kind: Kind, artifact: DerivedArtifact): Promise<Result<ReconcileReport>>;
     /**
      * Delete a record by `(kind, entityId)`. Non-temporal kinds physically delete
      * the file and return the deleted record's {@link MemoryId}. Temporal
@@ -2250,9 +3002,29 @@ export declare interface IMemoryStore {
 
 /**
  * Filter for {@link IMemoryStore.list}. All present fields are ANDed together.
+ *
+ * @remarks
+ * **At least one of `scope` / `kind` / `tag` must be present.** `asOf` is a
+ * temporal *projection*, not a narrowing — it collapses versions rather than
+ * excluding entities — so it does not satisfy the requirement on its own. A
+ * selection that narrows nothing fails with a message naming
+ * {@link scanEveryRecord}.
  * @public
  */
 export declare interface IMemoryStoreListFilter {
+    /**
+     * Never present on a narrowing filter.
+     *
+     * @remarks
+     * Exclusivity marker, paired with the `never`s on {@link IWholeVaultScan}.
+     * Without it `{ scanEveryRecord: true, kind }` type-checks — TypeScript's
+     * excess-property check on a union admits any property declared by *any*
+     * member — and `list` then takes the scan branch and silently discards the
+     * narrowing. Since the whole point of requiring a selection is that a
+     * whole-vault read must be deliberate, a call that reads the whole vault while
+     * *looking* narrowed is the one outcome this surface must not permit.
+     */
+    readonly scanEveryRecord?: never;
     /** Restrict to records in this scope. */
     readonly scope?: MemoryScopeKey;
     /** Restrict to records of this kind. */
@@ -2323,7 +3095,7 @@ export declare interface IMergeStrategy {
  * are each retriever's own concern.
  * @public
  */
-export declare function indexedRecordMatchesQuery(entry: IIndexedMemoryRecord, query: IMemoryQuery): boolean;
+export declare function indexedRecordMatchesQuery(entry: IIndexedMemoryEntry, query: IMemoryQuery): boolean;
 
 /**
  * How a candidate was ultimately written (or not) after resolution.
@@ -2376,6 +3148,8 @@ export declare class InMemoryCosineIndex implements IVectorIndex {
     static create(): Result<InMemoryCosineIndex>;
     /** {@inheritDoc IVectorIndex.add} */
     add(target: IEdgeTarget, vector: Float32Array): Promise<Result<string>>;
+    /** {@inheritDoc IVectorIndex.has} */
+    has(target: IEdgeTarget): Promise<Result<boolean>>;
     /** {@inheritDoc IVectorIndex.remove} */
     remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
     /** {@inheritDoc IVectorIndex.query} */
@@ -2408,6 +3182,11 @@ export declare class InMemoryCosineIndex implements IVectorIndex {
      * A {@link MemoryEmbedder} decline is not a failure under either mode: it is
      * counted on {@link IVectorRebuildReport.declined} and never appears in `skipped`.
      *
+     * **A `'fail'` failure carries the partial report on its `detail`** — the
+     * rollback still runs, so that report describes the aborted attempt rather than
+     * the (now empty) index. The one failure with no detail is a `list` failure,
+     * which disturbs nothing and has nothing to describe.
+     *
      * 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.
@@ -2416,7 +3195,7 @@ export declare class InMemoryCosineIndex implements IVectorIndex {
      * @param embed - The embedder applied to each record.
      * @param options - Rebuild options; omit for the historical `'fail'` behavior.
      */
-    rebuild(source: IMemoryRecordSource, embed: MemoryEmbedder, options?: IVectorRebuildOptions): Promise<Result<IVectorRebuildReport>>;
+    rebuild(source: IMemoryRecordSource, embed: MemoryEmbedder, options?: IVectorRebuildOptions): Promise<DetailedResult<IVectorRebuildReport, IVectorRebuildReport>>;
     /** Empty the index and forget the established dimension. */
     private _reset;
     /** The Euclidean magnitude (L2 norm) of a vector. */
@@ -2474,10 +3253,23 @@ export declare class InMemoryFragmentCosineIndex implements IFragmentVectorIndex
     static create(): Result<InMemoryFragmentCosineIndex>;
     /** {@inheritDoc IFragmentVectorIndex.addFragments} */
     addFragments(target: IEdgeTarget, fragments: ReadonlyArray<IEmbeddedFragment>): Promise<Result<number>>;
+    /** {@inheritDoc IFragmentVectorIndex.has} */
+    has(target: IEdgeTarget): Promise<Result<boolean>>;
     /** {@inheritDoc IFragmentVectorIndex.remove} */
     remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
     /** {@inheritDoc IFragmentVectorIndex.query} */
-    query(vector: Float32Array, topK: number, maxPerRecord?: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    query(vector: Float32Array, topK: number, options?: IFragmentQueryOptions): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    /**
+     * The records a query is allowed to score, honoring the `scope` / `id` narrowing.
+     *
+     * @remarks
+     * The single-record case is an O(1) map lookup rather than a scan, because the
+     * record map is keyed by `edgeTargetKey`. The scope-only case (a versioned kind's
+     * per-entity subtree) is a filtered walk — still bounded by the vault, but it
+     * scores only the entity's own fragments, which is what makes the caller's `topK`
+     * meaningful.
+     */
+    private _selectRecords;
     /**
      * Re-embed every record from `source` and rebuild the fragment index from
      * scratch. Clears the current contents (and the established dimension) first, so
@@ -2497,7 +3289,8 @@ export declare class InMemoryFragmentCosineIndex implements IFragmentVectorIndex
      * @param source - The scope-qualified record source to re-embed.
      * @param embed - The fragment embedder applied to each record.
      */
-    rebuild(source: IMemoryRecordSource, embed: FragmentEmbedder): Promise<Result<number>>;
+    /** {@inheritDoc IFragmentVectorIndex.rebuild} */
+    rebuild(source: IMemoryRecordSource, embed: FragmentEmbedder, options?: IVectorRebuildOptions): Promise<DetailedResult<IFragmentVectorRebuildReport, IFragmentVectorRebuildReport>>;
     /** Empty the index and forget the established dimension. */
     private _reset;
     /** The Euclidean magnitude (L2 norm) of a vector. */
@@ -2538,6 +3331,23 @@ export declare interface IProvenance {
     readonly [key: string]: unknown;
 }
 
+/** A `rank` reconcile: re-run the projector and restamp what changed. @public */
+export declare interface IRankReconcileReport extends IReconcileReportBase {
+    readonly artifact: 'rank';
+}
+
+/** What every reconcile reports, whatever the artifact. @public */
+export declare interface IReconcileReportBase {
+    /** The kind reconciled — named by the caller, so every count below is scalar. */
+    readonly kind: Kind;
+    /** Records of this kind considered. The denominator for everything else. */
+    readonly examined: number;
+    /** Records whose derived artifact was (re)produced by this call. */
+    readonly repaired: number;
+    /** Records that failed, with the error. A fault, never a decline. */
+    readonly failed: ReadonlyArray<ISkippedVectorRecord>;
+}
+
 /**
  * A candidate paired with its resolved reference id, handed to the relation
  * extractor so it can source edges from it.
@@ -2580,6 +3390,24 @@ export declare interface IRelationExtractor {
     relate(context: IRelationContext): Promise<Result<ReadonlyArray<ICandidateEdge>>>;
 }
 
+/**
+ * What every index-backed retriever needs: the index it selects over, and the
+ * resolver it materializes survivors through.
+ *
+ * @remarks
+ * The resolver is the whole of the partial-read migration for a caller that
+ * constructs retrievers directly — the index projection itself is invisible to
+ * anyone who only consumes `retrieve()`. `FileTreeMemoryStore` implements
+ * {@link IMemoryRecordResolver}, so wiring is `{ index, resolver: store }`.
+ * @public
+ */
+export declare interface IRetrieverCreateParams {
+    /** The derived index to select over. */
+    readonly index: IMemoryIndex;
+    /** Materializes the selected entries' bodies. */
+    readonly resolver: IMemoryRecordResolver;
+}
+
 /**
  * A record paired with its scope-qualified {@link IEdgeTarget | address}, as
  * yielded by {@link IMemoryRecordSource.list}. The address is required because
@@ -2613,9 +3441,7 @@ export declare interface ISemanticBackend {
  * Construction options for {@link SemanticRetriever.create}.
  * @public
  */
-export declare interface ISemanticRetrieverCreateParams {
-    /** The record index, used to resolve vector hits back to full records. */
-    readonly index: IMemoryIndex;
+export declare interface ISemanticRetrieverCreateParams extends IRetrieverCreateParams {
     /**
      * The semantic backend. When absent, the retriever reports
      * `supportsSemanticRecall: false` and a `query.semantic` request degrades
@@ -2668,7 +3494,7 @@ export declare function isTemporalIdentityCodec(codec: IIdentityCodec): codec is
  * divergence (MTM is flat yet has `entityId !== id`).
  * @public
  */
-export declare function isTemporalRecord(record: IMemoryRecord<unknown>): boolean;
+export declare function isTemporalRecord(record: IEnvelopeCarrier): boolean;
 
 /**
  * Whether a temporal record is a *current* version — its `temporal.invalid_at`
@@ -2676,7 +3502,7 @@ export declare function isTemporalRecord(record: IMemoryRecord<unknown>): boolea
  * current in this sense (returns `false`).
  * @public
  */
-export declare function isVersionCurrent(record: IMemoryRecord<unknown>): boolean;
+export declare function isVersionCurrent(record: IEnvelopeCarrier): boolean;
 
 /**
  * Whether a temporal record's validity interval contains `asOf` (epoch ms):
@@ -2685,7 +3511,13 @@ export declare function isVersionCurrent(record: IMemoryRecord<unknown>): boolea
  * record is never "valid at" a point (returns `false`).
  * @public
  */
-export declare function isVersionValidAt(record: IMemoryRecord<unknown>, asOf: number): boolean;
+export declare function isVersionValidAt(record: IEnvelopeCarrier, asOf: number): boolean;
+
+/**
+ * Whether a selection is the explicit whole-vault opt-out.
+ * @public
+ */
+export declare function isWholeVaultScan(selection: MemoryListSelection): selection is IWholeVaultScan;
 
 /**
  * Optional bi-temporal validity block on an envelope. Present only on
@@ -2769,6 +3601,32 @@ export declare interface IVectorIndex {
      * Return the `topK` nearest records to `vector`, in descending score order.
      */
     query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    /**
+     * Whether this index holds a vector for the scope-qualified `target`.
+     *
+     * @remarks
+     * On the contract because it is what makes a **targeted** repair possible, and
+     * the reason is sharper than convenience: the only other way to ask *"is this
+     * record indexed?"* is {@link IMemoryEnvelope.embeddingRef} — and that field is
+     * the store's **belief**, which is wrong in precisely the situation a repair
+     * runs in. A reopened vault backed by a fresh in-memory index carries an
+     * `embeddingRef` on every record while holding no vectors at all. **A repair
+     * that trusts the field it is repairing is not a repair.**
+     *
+     * It also makes a case *detectable* that an `embeddingRef`-only check cannot
+     * see at all: the index holds the vector but the envelope lost its reference
+     * (a failure swallowed after the vector was committed). That record needs its
+     * reference restamped and **no embedder call**, which is only knowable by
+     * asking the index.
+     *
+     * `Promise<Result<boolean>>`, unlike the synchronous {@link IVectorIndex.size},
+     * because the two are not the same kind of accessor and should not be made to
+     * look alike: `size` is a count both shipped implementations hold or can read
+     * without a failure mode, while `has` on a durable backend is a keyed query
+     * that can fail. Idempotent and side-effect-free; an absent target is
+     * `succeed(false)`, never a failure.
+     */
+    has(target: IEdgeTarget): Promise<Result<boolean>>;
     /**
      * The number of vectors currently held.
      *
@@ -2806,8 +3664,36 @@ export declare interface IVectorIndex {
      *
      * See {@link IVectorRebuildReport} for what it reports and
      * {@link IVectorRebuildOptions} for the failure mode.
-     */
-    rebuild(source: IMemoryRecordSource, embed: MemoryEmbedder, options?: IVectorRebuildOptions): Promise<Result<IVectorRebuildReport>>;
+     *
+     * **A failure carries the report too, on the `detail`** — coverage is most
+     * wanted exactly when a rebuild did not complete, and withholding it there made
+     * the answer depend on the error-handling mode rather than on the question. The
+     * `'fail'` contract itself is unchanged: it still resets, still aborts, still
+     * returns a failure. It simply also says what it had established before it
+     * stopped. See {@link IVectorRebuildReport} for how to read a report that
+     * arrived on a failure — it describes the attempt, not the surviving index.
+     *
+     * On success the report is the **value** — that is where it belongs, and the
+     * `detail` is not also populated. A failure carries no report when nothing was
+     * attempted: always a `source.list()` failure, and additionally whatever
+     * pre-loop step an implementation needs before it can start (the durable
+     * `SqliteVecVectorIndex` must clear its table, and a failure to do so is such a
+     * case). Those leave the existing index untouched, so an all-zero report would
+     * describe an index the call never disturbed.
+     *
+     * **A rebuild does NOT re-establish the vector dimension on a persistent
+     * index, and this is the one place the two shipped implementations genuinely
+     * differ.** The in-memory indexes forget their dimension when they reset, so a
+     * rebuild with a different-dimension embedder simply re-establishes it. A
+     * `vec0`-backed index cannot: its reset is a `DELETE FROM`, the table's
+     * declared dimension is part of its schema, and `vec0` has no `ALTER TABLE`.
+     * So a rebuild that changes dimension **succeeds in memory and fails on
+     * SQLite**, where it needs the same drop-and-re-index the package README
+     * prescribes for any schema change (drop the table, or point the index at a
+     * fresh `tableName`). Only embedding time is at risk — vectors are derived and
+     * the vault records remain authoritative.
+     */
+    rebuild(source: IMemoryRecordSource, embed: MemoryEmbedder, options?: IVectorRebuildOptions): Promise<DetailedResult<IVectorRebuildReport, IVectorRebuildReport>>;
 }
 
 /**
@@ -2883,26 +3769,141 @@ export declare interface IVectorRebuildOptions {
  * What a rebuild actually did — the structural answer to "is this index complete?".
  *
  * @remarks
- * A bare count cannot distinguish the three ways a record can be absent from the
- * index, and that distinction is the entire point: **`declined` was intentional,
- * `skipped` was a fault, and neither is the same as "never attempted"**. A caller
- * deriving coverage from a count alone cannot tell an embedder outage from a
- * deliberate policy, which is precisely the confusion this type exists to end.
+ * A bare count cannot distinguish the ways a record can be absent from the index,
+ * and that distinction is the entire point: **`declined` was intentional,
+ * `excluded` was never offered, `skipped` was a fault, and none of them is the
+ * same as "never attempted"**. A caller deriving coverage from a count alone
+ * cannot tell an embedder outage from a deliberate policy, which is precisely the
+ * confusion this type exists to end.
+ *
+ * **Every count in this report is resolved by kind.** A coverage report exists to
+ * answer *"is my coverage what I intended?"*, and a bare total cannot:
+ * `indexed: 500` reads identically whether the right kinds were indexed or a
+ * policy drift silently redirected coverage, and the same is true of every other
+ * count here. Totals are derivable by summing; the per-kind breakdown is not
+ * derivable from anything else — {@link IVectorQueryHit} carries no `kind`,
+ * {@link IVectorIndex.query} answers "what is near this" rather than "what is in
+ * here", and {@link IVectorIndex.size} is a scalar, so the index cannot be
+ * interrogated after the fact for any of them. **A new count added to this report
+ * is resolved by kind unless there is a stated reason it cannot be.**
+ *
+ * `indexed` is the count most tempting to leave bare and the most dangerous to,
+ * because it is the number a coverage surface actually renders: 500 bookkeeping
+ * rows and zero knowledge rows is a healthy-looking number for a catastrophically
+ * broken index.
+ *
+ * **Reading a report that arrived on a failure.** Under
+ * {@link VectorRebuildErrorMode | `onRecordError: 'fail'`} the report is handed
+ * back on the failure's `detail` — *after* the rollback has already run. It
+ * describes the attempt, not the surviving index: `indexed` names what had been
+ * established when the rebuild stopped, and the index itself now holds nothing. It
+ * is a diagnostic ("we were 340 knowledge rows in when the embedder died"), not a
+ * coverage statement. Only a report from a **successful** rebuild describes what
+ * the index holds.
  * @public
  */
 export declare interface IVectorRebuildReport {
-    /** Records embedded and added to the index. */
-    readonly indexed: number;
-    /** Records the embedder deliberately declined (resolved `undefined`). */
-    readonly declined: number;
+    /**
+     * Records embedded and added to the index, counted by {@link Kind}.
+     *
+     * @remarks
+     * A count of successful `add` calls, so it lines up with its per-record
+     * siblings and the buckets sum back to the listing. It is deliberately **not**
+     * read back off {@link IVectorIndex.size} at the end, which no implementation
+     * could resolve by kind anyway. The trade that makes: a `source` that lists the
+     * same `(scope, id)` twice contributes twice here while the index holds one
+     * vector, where a size read would have self-corrected. A source that does that
+     * is malformed, and a total that silently disagreed with the per-kind
+     * breakdown would be the worse failure.
+     */
+    readonly indexed: ReadonlyMap<Kind, number>;
+    /**
+     * Records the embedder deliberately declined (resolved `undefined`), counted by
+     * {@link Kind}. The embedder was called and answered — contrast `excluded`,
+     * where it never was.
+     */
+    readonly declined: ReadonlyMap<Kind, number>;
+    /**
+     * Records the `source` filtered out before the rebuild ever saw them, counted by
+     * {@link Kind} — for a store-backed source, the kinds outside
+     * {@link IMemoryStore.embedsKind | embedsKind}.
+     *
+     * **Optional, and the optionality is semantic rather than cosmetic**: it is the
+     * one count a rebuild genuinely cannot know for itself, because the decision is
+     * made upstream in the source. `undefined` means *this source does not report
+     * exclusions* — distinct from an empty map, which means *this source reports
+     * them and excluded nothing*. `indexed` and `declined` are knowable by
+     * construction (the rebuild either added the vector or the embedder answered)
+     * and so are never optional.
+     */
+    readonly excluded?: ReadonlyMap<Kind, number>;
     /**
      * Records whose embedding or add FAILED and were skipped. Non-empty only under
      * {@link VectorRebuildErrorMode | `onRecordError: 'skip'`} — under `'fail'` the
-     * first failure aborts the rebuild and no report is returned at all.
+     * first failure aborts the rebuild, so a `'fail'` report names the casualty in
+     * its failure message rather than here.
+     *
+     * Per-record and carrying the error, so it already implies the per-kind
+     * breakdown the counts above spell out; that is the stated reason this one field
+     * is not a `ReadonlyMap<Kind, number>`.
      */
     readonly skipped: ReadonlyArray<ISkippedVectorRecord>;
 }
 
+/**
+ * A record-vector reconcile.
+ * @public
+ */
+export declare interface IVectorReconcileReport extends IReconcileReportBase {
+    readonly artifact: 'record-vector';
+    /**
+     * Records the index already held and which needed **no embedder call** — the
+     * whole point of a targeted repair, and the number that shows what it saved
+     * against a `rebuild`.
+     */
+    readonly alreadyIndexed: number;
+    /**
+     * Records whose vector the index held but whose envelope had **lost its
+     * `embeddingRef`** — repaired by restamping the reference, with no embedder
+     * call.
+     *
+     * @remarks
+     * This case is invisible to an `embeddingRef`-only check, which is one of the
+     * two reasons `IVectorIndex.has` is on the contract: a reference-absent record
+     * looks identical to a never-embedded one until you ask the index.
+     */
+    readonly restamped: number;
+    /** Records the embedder intentionally declined. Not a failure, not a gap. */
+    readonly declined: number;
+}
+
+/**
+ * The named, deliberately uncomfortable opt-out from
+ * {@link IMemoryStore.list}'s narrowing requirement — build one with
+ * {@link scanEveryRecord}.
+ * @public
+ */
+export declare interface IWholeVaultScan {
+    /** Discriminator. Always `true`; produced only by {@link scanEveryRecord}. */
+    readonly scanEveryRecord: true;
+    /**
+     * Never present on a whole-vault scan — see
+     * {@link IMemoryStoreListFilter.scanEveryRecord} for why these markers exist.
+     * A scan that also carried a narrowing axis would have that axis dropped.
+     */
+    readonly scope?: never;
+    /** Never present on a whole-vault scan. See {@link IWholeVaultScan.scope}. */
+    readonly kind?: never;
+    /** Never present on a whole-vault scan. See {@link IWholeVaultScan.scope}. */
+    readonly tag?: never;
+    /**
+     * Optional temporal projection, exactly as on {@link IMemoryStoreListFilter}.
+     * NOT excluded, because `asOf` projects rather than narrows and composes with
+     * a whole-vault read exactly as it does with a filtered one.
+     */
+    readonly asOf?: number;
+}
+
 /**
  * A per-kind write policy, injected at store construction. Invoked AFTER
  * content-hash dedup (dedup is always pre-policy). The policy decides
@@ -3074,6 +4075,13 @@ export declare class KnowledgeLwwPolicy implements IWritePolicy {
     private _rebuild;
 }
 
+/**
+ * The {@link limitRecords} window, applied to entries — used on the
+ * no-body-filter path so paging happens before anything is read.
+ * @public
+ */
+export declare function limitEntries(entries: ReadonlyArray<IIndexedMemoryEntry>, limit?: number, offset?: number): ReadonlyArray<IIndexedMemoryEntry>;
+
 /**
  * Apply the `{ offset, limit }` page window to an ordered record set. Applied
  * last, after ordering, so it always takes a stable window of the ordered
@@ -3130,22 +4138,16 @@ export declare const LINK_TRAVERSAL_UNWIRED_MESSAGE: string;
  */
 export declare class LinkTraversalRetriever implements IMemoryRetriever {
     private readonly _index;
+    private readonly _resolver;
     private constructor();
     /** Family-convention factory. */
-    static create(index: IMemoryIndex): Result<LinkTraversalRetriever>;
+    static create(params: IRetrieverCreateParams): Result<LinkTraversalRetriever>;
     /** {@inheritDoc IMemoryRetriever.capabilities} */
     get capabilities(): IMemoryRetrieverCapabilities;
     /** {@inheritDoc IMemoryRetriever.retrieve} */
     retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
     /** Run the bounded, cycle-safe BFS and post-filter the reached records. */
     private _traverse;
-    /**
-     * Group the index's entries by their scope-qualified {@link edgeTargetKey}
-     * `(scope, id)` composite. Each composite is the index's primary key, so it maps
-     * to exactly one entry — two records that reuse a filename stem across scopes
-     * (e.g. `turn-0` in two conversations) get distinct keys and never collide.
-     */
-    private _indexByKey;
     /** Outbound neighbors: the scope-qualified targets of every edge on the record at `node`. */
     private _outbound;
     /** Inbound neighbors: the scope-qualified sources whose edges point AT `node` (the backlinks). */
@@ -3185,6 +4187,45 @@ export declare class LtmIdentityCodec implements IIdentityCodec {
     verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<true>;
 }
 
+/**
+ * Materialize entries through the resolver, dropping any that have vanished
+ * since selection — a concurrent delete between selecting an envelope and
+ * reading its body is a legitimate race and yields a shorter list, not an error.
+ * A read that FAILS is a real fault and propagates.
+ * @public
+ */
+export declare function materializeEntries(entries: ReadonlyArray<IIndexedMemoryEntry>, resolver: IMemoryRecordResolver): Result<ReadonlyArray<IMemoryRecord<unknown>>>;
+
+/**
+ * Materialize a selected, ordered page — **applying `query.filter` and paging in
+ * the right order**, which is the whole reason this is shared rather than
+ * open-coded per retriever.
+ *
+ * @remarks
+ * Two paths, and the choice is forced by where the predicate can run:
+ *
+ * - **No `filter`** — order and page over *envelopes*, then read only the page.
+ *   `limit` bounds the READ, not just the result.
+ * - **With `filter`** — the predicate takes a whole record, so every
+ *   envelope-survivor must be read first, then filtered, then paged. Paging
+ *   before filtering would return fewer than `limit` rows for no reason a caller
+ *   could see.
+ *
+ * **Every retriever must route through this.** `indexedRecordMatchesQuery`
+ * structurally *cannot* apply `filter` — it is handed an envelope — so a
+ * retriever that pre-filters with it and then materializes on its own silently
+ * ignores the predicate. That regression shipped once, in the stream that moved
+ * `filter` out of the pre-filter; this function exists so it cannot recur.
+ *
+ * @param selected - Entries surviving the envelope pre-filter.
+ * @param query - The query whose `filter` / `orderBy` / `limit` / `offset` apply.
+ * @param resolver - Body resolver.
+ * @param order - Applied to whichever collection is paged; identity is legal for
+ * a retriever whose ordering is intrinsic (semantic score, traversal order).
+ * @public
+ */
+export declare function materializePage<T extends IIndexedMemoryEntry>(selected: ReadonlyArray<T>, query: IMemoryQuery, resolver: IMemoryRecordResolver, order?: (candidates: ReadonlyArray<T>) => ReadonlyArray<T>): Result<ReadonlyArray<IMemoryRecord<unknown>>>;
+
 /**
  * Bounded-ring write policy for the experience (memory) kind families.
  * Admission accepts until `maxRecords` is reached, then evicts the oldest
@@ -3344,7 +4385,10 @@ export declare type MemoryId = Brand<string, 'MemoryId'>;
  * @public
  */
 export declare class MemoryIndex implements IMemoryIndex {
-    /** Primary store: `(scope, id)` composite key → indexed entry. */
+    /**
+     * Primary store: `(scope, id)` composite key → indexed entry. Holds the
+     * PROJECTED form, so the index never retains a body.
+     */
     private readonly _byKey;
     /** kind → set of composite keys. */
     private readonly _byKind;
@@ -3371,19 +4415,21 @@ export declare class MemoryIndex implements IMemoryIndex {
      */
     private static _keyOf;
     /** {@inheritDoc IMemoryIndex.rebuild} */
-    rebuild(entries: ReadonlyArray<IIndexedMemoryRecord>): Result<number>;
+    rebuild(entries: ReadonlyArray<IIndexedMemoryEntry>): Result<number>;
     /** {@inheritDoc IMemoryIndex.patch} */
     patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord>;
     /** {@inheritDoc IMemoryIndex.entries} */
-    entries(): ReadonlyArray<IIndexedMemoryRecord>;
+    entries(): ReadonlyArray<IIndexedMemoryEntry>;
+    /** {@inheritDoc IMemoryIndex.get} */
+    get(target: IEdgeTarget): IIndexedMemoryEntry | undefined;
     /** {@inheritDoc IMemoryIndex.byKind} */
-    byKind(kind: Kind): ReadonlyArray<IMemoryRecord<unknown>>;
+    byKind(kind: Kind): ReadonlyArray<IIndexedMemoryEntry>;
     /** {@inheritDoc IMemoryIndex.byTag} */
-    byTag(tag: Tag): ReadonlyArray<IMemoryRecord<unknown>>;
+    byTag(tag: Tag): ReadonlyArray<IIndexedMemoryEntry>;
     /** {@inheritDoc IMemoryIndex.byRecency} */
-    byRecency(): ReadonlyArray<IMemoryRecord<unknown>>;
+    byRecency(): ReadonlyArray<IIndexedMemoryEntry>;
     /** {@inheritDoc IMemoryIndex.byRank} */
-    byRank(): ReadonlyArray<IMemoryRecord<unknown>>;
+    byRank(): ReadonlyArray<IIndexedMemoryEntry>;
     /** {@inheritDoc IMemoryIndex.backlinks} */
     backlinks(target: IEdgeTarget): ReadonlyArray<IEdgeTarget>;
     /**
@@ -3401,6 +4447,8 @@ export declare class MemoryIndex implements IMemoryIndex {
      * approach; the sort is over the in-memory index, never a filesystem walk.
      */
     private _rankOrdered;
+    /** Resolve composite keys to their entries, skipping any that are absent. */
+    private static _resolve;
     /**
      * Rank-descending comparator with an absent-`rank`-last rule and a recency
      * (`updated`, then `seq`) tiebreak. Duplicated from the retrieve packlet's
@@ -3603,6 +4651,13 @@ export declare class MemoryIngestOrchestrator implements IMemoryIngestOrchestrat
     private static _asStringBody;
 }
 
+/**
+ * What {@link IMemoryStore.list} accepts: a narrowing filter, or the explicit
+ * whole-vault scan.
+ * @public
+ */
+export declare type MemoryListSelection = IMemoryStoreListFilter | IWholeVaultScan;
+
 /**
  * The outcome of the observed operation.
  * @public
@@ -3812,7 +4867,7 @@ export declare const NON_SEMANTIC_CAPABILITIES: IMemoryRetrieverCapabilities;
  * default, byte-identical to the pre-`orderBy` behavior).
  * @public
  */
-export declare function orderingCompare(orderBy?: IMemoryQuery['orderBy']): (a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>) => number;
+export declare function orderingCompare(orderBy?: IMemoryQuery['orderBy']): (a: IEnvelopeCarrier, b: IEnvelopeCarrier) => number;
 
 /**
  * Parse a complete memory file into a typed {@link IMemoryRecord}. Splits the
@@ -3852,7 +4907,7 @@ export declare type QueryEmbedder = (text: string) => Promise<Result<Float32Arra
  * index's rank-view ordering.
  * @public
  */
-export declare function rankCompare(a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>): number;
+export declare function rankCompare(a: IEnvelopeCarrier, b: IEnvelopeCarrier): number;
 
 /**
  * A per-kind host projection from a fully-resolved (post-merge) memory record
@@ -3864,7 +4919,7 @@ export declare function rankCompare(a: IMemoryRecord<unknown>, b: IMemoryRecord<
  * 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`.
+ * already exist, call `IMemoryStore.reconcile(kind, 'rank')`.
  * @public
  */
 export declare type RankProjector = (record: IMemoryRecord<unknown>) => number;
@@ -3874,7 +4929,7 @@ export declare type RankProjector = (record: IMemoryRecord<unknown>) => number;
  * equal-`updated` records sort deterministically. Mirrors the B1 index ordering.
  * @public
  */
-export declare function recencyCompare(a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>): number;
+export declare function recencyCompare(a: IEnvelopeCarrier, b: IEnvelopeCarrier): number;
 
 /**
  * Returns records matching the query's scope / kind / tag / provenance-source / predicate filters,
@@ -3884,15 +4939,22 @@ export declare function recencyCompare(a: IMemoryRecord<unknown>, b: IMemoryReco
  */
 export declare class RecencyRetriever implements IMemoryRetriever {
     private readonly _index;
+    private readonly _resolver;
     private constructor();
     /** {@inheritDoc IMemoryRetriever.capabilities} */
     get capabilities(): IMemoryRetrieverCapabilities;
     /** Family-convention factory. */
-    static create(index: IMemoryIndex): Result<RecencyRetriever>;
+    static create(params: IRetrieverCreateParams): Result<RecencyRetriever>;
     /** {@inheritDoc IMemoryRetriever.retrieve} */
     retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
 }
 
+/**
+ * What a {@link IMemoryStore.reconcile} established, discriminated by artifact.
+ * @public
+ */
+export declare type ReconcileReport = IRankReconcileReport | IVectorReconcileReport | IFragmentReconcileReport;
+
 /**
  * The four dedup verdicts a {@link IEntityResolver} (or fgv's exact-match layer)
  * returns for a candidate. See the design note §3 for the verdict → write
@@ -3914,6 +4976,53 @@ export declare type ResolutionVerdict = {
     readonly target: IEdgeTarget;
 };
 
+/**
+ * The shared select → order → page → materialize pipeline every non-semantic
+ * retriever runs, and the one place the body-vs-envelope ordering decision lives.
+ *
+ * @public
+ * @remarks
+ * **Without `query.filter`, ordering and paging happen over envelopes and only
+ * the page is materialized** — so `limit` genuinely bounds the number of records
+ * read, not merely the number returned. That is what makes `limit` a legitimate
+ * narrowing axis rather than a loophole, and it is conditional on the ordering
+ * key being an envelope field: both shipped comparators (`recencyCompare`,
+ * `rankCompare`) read `updated` / `seq` / `rank` and qualify. **An ordering that
+ * keyed on a body field could not use this path** and would have to sort after
+ * materialization, at which point `limit` bounds the result and not the read.
+ *
+ * **With `query.filter`, every envelope-survivor must be materialized first**,
+ * because the predicate takes a whole record. Semantics are preserved exactly;
+ * the cost is not. Pair `filter` with an envelope axis when the read cost
+ * matters.
+ */
+export declare function resolveQuery(entries: ReadonlyArray<IIndexedMemoryEntry>, query: IMemoryQuery, resolver: IMemoryRecordResolver): Result<ReadonlyArray<IMemoryRecord<unknown>>>;
+
+/**
+ * Ask {@link IMemoryStore.list} for **every record in the vault**, bodies
+ * included.
+ *
+ * @remarks
+ * `list` requires a selection and rejects one that narrows nothing, so this is
+ * the only way to get the whole vault — and that is the point. Since the index
+ * holds envelopes only, `list` materializes every survivor from storage, so an
+ * unnarrowed call reads one file per record. Making it impossible to write by
+ * accident is worth more than making it fast.
+ *
+ * It is named for what it costs rather than for what it returns, and it is
+ * greppable: `scanEveryRecord` enumerates every whole-vault read in a codebase in
+ * one search. This mirrors `@fgv/ts-extras`' `safer-fetch`, where `addressGuard`
+ * is required with no default and `allowAnyAddress()` is the named opt-out.
+ *
+ * **If you only need to select, you do not need this.** Use
+ * {@link IMemoryStore.listEntries}, which returns every entry's scope and
+ * envelope, reads no files, and needs no selection.
+ * @public
+ */
+export declare function scanEveryRecord(options?: {
+    readonly asOf?: number;
+}): IWholeVaultScan;
+
 /**
  * The reference {@link IMergeStrategy}: a score-union. Every record is scored by
  * the number of composed result sets it appears in (deduplicated by
@@ -3940,7 +5049,7 @@ export declare class ScoreUnionMergeStrategy implements IMergeStrategy {
  * unlimited).
  * @public
  */
-export declare function selectByQuery(entries: ReadonlyArray<IIndexedMemoryRecord>, query: IMemoryQuery): IMemoryRecord<unknown>[];
+export declare function selectByQuery(entries: ReadonlyArray<IIndexedMemoryEntry>, query: IMemoryQuery): IIndexedMemoryEntry[];
 
 /**
  * Select the current version from a set of an entity's versions: the newest
@@ -3948,7 +5057,7 @@ export declare function selectByQuery(entries: ReadonlyArray<IIndexedMemoryRecor
  * entity has no current version (fully invalidated / soft-deleted, or empty).
  * @public
  */
-export declare function selectCurrentVersion(versions: ReadonlyArray<IMemoryRecord<unknown>>): IMemoryRecord<unknown> | undefined;
+export declare function selectCurrentVersion<T extends IEnvelopeCarrier>(versions: ReadonlyArray<T>): T | undefined;
 
 /**
  * Select the version of an entity valid at `asOf` (epoch ms): the newest
@@ -3956,7 +5065,7 @@ export declare function selectCurrentVersion(versions: ReadonlyArray<IMemoryReco
  * when no version was valid at that instant.
  * @public
  */
-export declare function selectVersionAsOf(versions: ReadonlyArray<IMemoryRecord<unknown>>, asOf: number): IMemoryRecord<unknown> | undefined;
+export declare function selectVersionAsOf<T extends IEnvelopeCarrier>(versions: ReadonlyArray<T>, asOf: number): T | undefined;
 
 /**
  * The loud-degradation message a retriever returns when `query.semantic` is set
@@ -3979,6 +5088,7 @@ export declare const SEMANTIC_UNWIRED_MESSAGE: string;
  */
 export declare class SemanticRetriever implements IMemoryRetriever {
     private readonly _index;
+    private readonly _resolver;
     private readonly _backend;
     private constructor();
     /** {@inheritDoc IMemoryRetriever.capabilities} */
@@ -4050,11 +5160,12 @@ export declare type StoreStampedEnvelopeField = 'id' | 'seq' | 'contentHash' | '
  */
 export declare class StructuredFilterRetriever implements IMemoryRetriever {
     private readonly _index;
+    private readonly _resolver;
     private constructor();
     /** {@inheritDoc IMemoryRetriever.capabilities} */
     get capabilities(): IMemoryRetrieverCapabilities;
     /** Family-convention factory. */
-    static create(index: IMemoryIndex): Result<StructuredFilterRetriever>;
+    static create(params: IRetrieverCreateParams): Result<StructuredFilterRetriever>;
     /** {@inheritDoc IMemoryRetriever.retrieve} */
     retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
 }
@@ -4074,11 +5185,12 @@ export declare type Tag = Brand<string, 'Tag'>;
  */
 export declare class TagRetriever implements IMemoryRetriever {
     private readonly _index;
+    private readonly _resolver;
     private constructor();
     /** {@inheritDoc IMemoryRetriever.capabilities} */
     get capabilities(): IMemoryRetrieverCapabilities;
     /** Family-convention factory. */
-    static create(index: IMemoryIndex): Result<TagRetriever>;
+    static create(params: IRetrieverCreateParams): Result<TagRetriever>;
     /** {@inheritDoc IMemoryRetriever.retrieve} */
     retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
 }