@avantf/dsh-mem 0.6.0 → 0.6.2

package/lib/index.js

@@ -708,7 +708,8 @@ const AdminUnion = z.discriminatedUnion("action", [
 	z.object({ action: z.literal("vectors_diagnose") }),
 	z.object({
 		action: z.literal("vectors_fix"),
-		dry_run: z.boolean().optional().describe("true=只诊断不写入；可选，默认 false。")
+		dry_run: z.boolean().optional().describe("true=只诊断不写入；可选，默认 false。"),
+		store: z.enum(["memory", "knowledge"]).optional().describe("只修某一个库（memory / knowledge）；省略=两库都修。")
 	}),
 	z.object({ action: z.literal("contradict_check") }),
 	z.object({
@@ -1324,6 +1325,170 @@ function promptTextWarnings(sections) {
 	return out;
 }
 //#endregion
+//#region lib/types/interface_gate.js
+/** Read one member without letting a hostile module's getter escape. */
+function member(module, name) {
+	try {
+		return module?.[name];
+	} catch {
+		return;
+	}
+}
+function cannotTell(reason) {
+	return {
+		status: "cannot-tell",
+		reason
+	};
+}
+/**
+* Whether the base's shared capabilities may be used under `verdict`.
+*
+* The ONE mapping from the gate's verdict to the loader's decision, exported so it is asserted
+* directly and the loader and its test cannot drift: only `incompatible` withholds the base;
+* `cannot-tell` does not, because it is not a negative answer. A `false` here is still a DEGRADATION
+* (own prompt defaults, gate skipped, legacy provisioning), never a refused mount.
+*/
+function baseIsUsable(verdict) {
+	return verdict.status !== "incompatible";
+}
+/**
+* Where the build's bake record sits when no explicit URL is given: beside the built ENTRY
+* (`lib/index.js`), which is where `scripts/link-envinit.mjs` writes it. A per-file `tsc` emit of
+* this module lives one directory below that entry and looks one level up; the first readable record
+* wins. Under `vitest` (running from `src/`) neither exists, which is the correct "not baked".
+*/
+const BAKED_CANDIDATES = ["./interface-version.json", "../interface-version.json"];
+/**
+* Read this artifact's baked requirement through the loaded base's own reader.
+* @param read - the base's `readInterfaceRequirement`, taken off the loaded module.
+* @param bakedUrl - test seam: read EXACTLY this record instead of walking {@link BAKED_CANDIDATES}.
+*/
+function requirementOf(read, bakedUrl) {
+	const candidates = bakedUrl === void 0 ? BAKED_CANDIDATES.map((relative) => new URL(relative, import.meta.url)) : [bakedUrl];
+	for (const url of candidates) {
+		let requirement;
+		try {
+			requirement = read(url);
+		} catch {
+			continue;
+		}
+		const version = requirement?.interfaceVersion;
+		if (typeof version === "number" && Number.isInteger(version) && version > 0) return { interfaceVersion: version };
+	}
+}
+/**
+* Ask the loaded base whether it implements the interface generation this artifact was built for.
+*
+* @param module - the loaded base module (only `checkInterface` / `readInterfaceRequirement` are
+*   touched, each through a guarded read).
+* @param bakedUrl - test seam: the bake record to read; production leaves it undefined.
+* @returns a verdict that is never `incompatible` unless BOTH sides were readable and differ, and
+*   never a throw.
+*/
+function interfaceVerdict(module, bakedUrl) {
+	const check = member(module, "checkInterface");
+	const read = member(module, "readInterfaceRequirement");
+	if (typeof check !== "function" || typeof read !== "function") return cannotTell("the loaded base has no interface gate (checkInterface / readInterfaceRequirement missing) — it predates the runtime interface contract, so which generation it implements cannot be told");
+	const requirement = requirementOf(read, bakedUrl);
+	if (requirement === void 0) return cannotTell("this build has no baked interface requirement (lib/interface-version.json is missing or malformed), so the runtime interface gate cannot run");
+	let verdict;
+	try {
+		verdict = check(requirement.interfaceVersion, module);
+	} catch {
+		return cannotTell("the loaded base threw while judging the interface generation");
+	}
+	const status = verdict?.status;
+	if (status !== "ok" && status !== "incompatible" && status !== "cannot-tell") return cannotTell("the loaded base returned no usable interface verdict");
+	return verdict;
+}
+/** Emit a warning without ever letting the logger turn it into a crash. */
+function warn$1(log, message) {
+	try {
+		log?.warn(message);
+	} catch {}
+}
+function reasonOf$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Run the runtime interface gate and answer whether the loaded base's shared capabilities may be
+* used.
+*
+* `false` is a DEGRADATION the caller answers by taking its own full-degradation route (no runtime,
+* own prompt defaults, the compatibility gate skipped, legacy provisioning) — never a refused mount,
+* and never a throw. `cannot-tell` warns and answers `true`: "cannot tell" is not a negative answer,
+* so the base is used normally. The verdict's own reason is the base's; only the surrounding sentence
+* is the caller's ({@link DegradeWords}).
+*/
+function gateOrDegrade(module, log, words) {
+	const verdict = interfaceVerdict(module);
+	if (!baseIsUsable(verdict)) {
+		warn$1(log, `${words.prefix} WARNING — interface: ${verdict.reason ?? "the loaded base implements another interface generation"}; the base's shared capabilities are NOT used (${words.withheld}) and the plugin mounts anyway`);
+		return false;
+	}
+	if (verdict.status === "cannot-tell") warn$1(log, `${words.prefix} WARNING — interface: ${verdict.reason ?? "the interface generation cannot be told"}; using the loaded base anyway ("cannot tell" is never "incompatible")`);
+	return true;
+}
+/**
+* The guard that makes a loader's "never throws" true: every failure is one warning plus
+* `undefined`. The caller owns the sentence's tail (`words`) and its own cache discipline — a
+* FAILED load is not cached, so this must return `undefined` rather than reject (see
+* {@link createLoadCache}).
+*/
+async function loadGuarded(options, loadOnce, log, words) {
+	try {
+		return await loadOnce(options);
+	} catch (error) {
+		warn$1(log, `${words.prefix} WARNING — environment initialisation failed (${reasonOf$1(error)}); ${words.loadFailure}`);
+		return;
+	}
+}
+/**
+* Wrap a guarded loader in the cache discipline both startups share: the first call runs it, every
+* later and concurrent call shares its result, and a FAILED load is NOT cached. A failure is "cannot
+* tell", not a verdict — and it may be transient (offline at boot, a half-written install) — so a
+* profile reload, or a second instance in the same process, retries instead of replaying the first
+* failure for the whole process lifetime.
+*/
+function createLoadCache(guarded) {
+	let loaded;
+	let loading;
+	return {
+		load(options) {
+			if (loaded !== void 0) return Promise.resolve(loaded);
+			if (loading !== void 0) return loading;
+			loading = guarded(options).then((runtime) => {
+				if (runtime === void 0) loading = void 0;
+				else loaded = runtime;
+				return runtime;
+			}, () => {
+				loading = void 0;
+			});
+			return loading;
+		},
+		clear() {
+			loaded = void 0;
+			loading = void 0;
+		}
+	};
+}
+/**
+* Whether a Cordis context is still alive.
+*
+* Cordis clears `fiber.uid` on disposal, and every later context call then throws
+* `INACTIVE_EFFECT`. `apply` awaits environment preparation, so a profile reload or unload can land
+* inside that window and half-register a plugin (the Remote face cannot be rolled back). A fiberless
+* stub counts as active: an unknown shape is "cannot tell", never "disposed".
+*
+* Generic Cordis liveness rather than interface-gate knowledge — but the two plugins' startup paths
+* share it byte-for-byte, so it lives with their one shared shim, where the two readings of "is my
+* context alive" cannot drift.
+*/
+function stillActive(ctx) {
+	const fiber = ctx?.fiber;
+	return fiber === void 0 || fiber.uid !== null;
+}
+//#endregion
 //#region lib/types/hints.js
 /**
 * The plugin's CONDITIONAL hint: ONE line, contributed only when either store already holds
@@ -3687,6 +3852,79 @@ async function dispatchToolKey(rt, key, args) {
 	if (dispatch === void 0) throw new Error(`unknown tool key ${key}`);
 	return dispatch(rt, args);
 }
+/**
+* The ONE model-facing boundary: validate against the contract spec, dispatch the key, and shape the
+* result into the agent envelope.
+*
+* Every model-facing surface shares this — the DSH tool runner (`@avantf/dsh-mem`) and the MCP
+* server — because the envelope is `ToolEnvelope`, a wire shape: an MCP caller and a DSH caller
+* asking the same question must get the same fields. It used to live only in the plugin, so the MCP
+* surface re-implemented it and the two could drift field by field.
+*
+* What stays in the CALLERS is everything AROUND the envelope: MCP's `textResult`/`isError` wrapper
+* and the plugin's `present` view plus its Remote gateway. The Remote gateway is deliberately NOT
+* routed through here (`mem/DESIGN.md` §239: it keeps `mem_admin`'s retention diagnostics and uses
+* the wire error type, not `toolErr`).
+*
+* A validation failure answers `validationError` (named for the spec), an unknown key answers
+* `toolErr`, and a throwing runtime call answers `toolErr` too — a raw exception never escapes.
+*/
+async function runToolSpec$1(rt, spec, args) {
+	const parsed = spec.input.safeParse(args ?? {});
+	if (!parsed.success) return validationError(spec.name, parsed.error.issues);
+	if (!supportsToolKey(spec.key)) return toolErr(`unknown tool ${spec.key}`);
+	try {
+		const value = await dispatchToolKey(rt, spec.key, parsed.data);
+		return toolOk(modelFacingToolResult(spec.key, parsed.data.action, value));
+	} catch (error) {
+		return toolErr(error);
+	}
+}
+//#endregion
+//#region ../core/lib/trustHeartbeat.js
+/**
+* The trust heartbeat: the interval beat that advances the active-day clock and performs the
+* settle / forget / idle / purge sweeps (TRUST_MODEL.md §5), shared by the DSH plugin and the MCP
+* server.
+*
+* The two surfaces used to install it separately, and the copies drifted in exactly the places a
+* copy drifts: the wording of the failure line and the work each beat does after the tick. The tick
+* itself — the one thing that MUST be identical, because it is the trust clock — is what lives
+* here. The differences are data: {@link TrustHeartbeatOptions.onBeat} is the extra work (the plugin
+* sweeps entities and retries the vector migration), {@link TrustHeartbeatOptions.tickFailed} is how
+* that surface names a failed sweep.
+*
+* `heartbeatMinutes <= 0` is the caller's decision, not this function's: a surface that disables the
+* beat also decides whether it logs the interval line.
+*
+* Zero dependencies beyond `setInterval` so it stays in the engine (the plugin's index and the MCP
+* entry both consume it).
+*/
+/** The generic one-line reason for a caught value. */
+function messageOf$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Install the heartbeat and return its disposer.
+*
+* A `trustTick` that throws is warned about and swallowed: a failed sweep must never take the host
+* or the server down, and it must not be invisible either — a trust clock that stopped advancing
+* shows up much later as facts that never settle, forget or purge. The timer is `unref`'d where the
+* runtime supports it, so it never holds a process open by itself.
+*/
+function installTrustHeartbeat(options) {
+	const timer = setInterval(() => {
+		try {
+			options.memory.trustTick();
+		} catch (error) {
+			options.logger.warn((options.tickFailed ?? ((message) => `trust tick failed: ${message}`))(messageOf$1(error)));
+		}
+		options.onBeat?.();
+	}, options.heartbeatMinutes * 6e4);
+	const unref = timer.unref;
+	if (typeof unref === "function") unref.call(timer);
+	return () => clearInterval(timer);
+}
 //#endregion
 //#region ../retrieval-core/lib/representation.js
 /**
@@ -6870,6 +7108,18 @@ function probeTerms(text, holds, stopAt = Number.POSITIVE_INFINITY) {
 		matched
 	};
 }
+/**
+* The store probe both stores' `lexicalProbe` used to spell out verbatim: build THIS store's MATCH
+* expression for one term (the tokenizer is a property of the store's FTS table) and ask that
+* table whether anything holds it. `probeTerms` owns the term set and the counting; this owns the
+* one part that has to differ, which is now a single `holds` closure per store.
+*/
+function probeStoreTerms(text, tokenizer, holds, stopAt = Number.POSITIVE_INFINITY) {
+	return probeTerms(text, (term) => {
+		const fts = buildFtsQuery(term, tokenizer);
+		return fts !== null && holds(fts);
+	}, stopAt);
+}
 //#endregion
 //#region ../core/lib/store/self_query.js
 /**
@@ -7393,6 +7643,60 @@ async function hybridSearch(deps, plan) {
 	};
 }
 /**
+* Map a store's search arguments onto {@link HybridPlan} and run {@link hybridSearch}. ONE copy.
+*
+* Before this, `MemoryStore.search` and `KnowledgeStore.search` carried the mapping verbatim side by
+* side: the same field list, the same conditional spreads, the same call. That list is part of the
+* orchestrator's contract, so an option added to one entry point and not the other would silently
+* make the two stores query differently — the same shape of drift this module already documents
+* (`NaN` limit, `over_fetch_factor`, unrecorded capped legs).
+*
+* The conditional spreads are deliberate, not cosmetic: a caller that did not pass `overFetch` /
+* `includeScores` / `relaxLegs` / `rewriteQuery` leaves the plan key ABSENT rather than
+* present-with-`undefined`. The orchestrator reads all four through `??` / `=== true` today, so the
+* two are indistinguishable now — but the plan is a contract, and widening it with keys the caller
+* never set is how "absent means default" decays into "present-undefined means set to nothing".
+*/
+async function runHybridSearch(deps, query, fields) {
+	return hybridSearch(deps, hybridPlanOf(query, fields));
+}
+/**
+* The mapping itself, separated from the call so it can be pinned directly: the contract here is
+* the SHAPE of the plan (which keys exist), which no behavioural assertion inside `hybridSearch`
+* could observe once every optional field is read through `??` / `=== true`.
+*/
+function hybridPlanOf(query, fields) {
+	return {
+		query,
+		limit: fields?.limit,
+		...fields?.overFetch === void 0 ? {} : { overFetch: fields.overFetch },
+		maxTokens: fields?.maxTokens,
+		queryVector: fields?.queryVector,
+		recordStats: fields?.recordStats,
+		floors: fields?.floors,
+		...fields?.includeScores === void 0 ? {} : { includeScores: fields.includeScores },
+		...fields?.relaxLegs === void 0 ? {} : { relaxLegs: fields.relaxLegs },
+		...fields?.rewriteQuery === void 0 ? {} : { rewriteQuery: fields.rewriteQuery }
+	};
+}
+/**
+* Build a store's {@link HybridDeps} — the ONE construction site for the contract fields both stores
+* share (`kind` / `config` / `semantic` / `legs` / `texts` / `hits` / `onReturn`). The per-store half
+* is `parts`; the stores used to spell the whole object out twice, so a new required `HybridDeps`
+* field was a change to remember in two places.
+*/
+function makeHybridDeps(kind, config, semantic, parts) {
+	return {
+		kind,
+		config,
+		semantic,
+		legs: parts.legs,
+		texts: parts.texts,
+		hits: parts.hits,
+		...parts.onReturn === void 0 ? {} : { onReturn: parts.onReturn }
+	};
+}
+/**
 * P-01: put the fused per-leg evidence onto the caller-facing hits.
 *
 * Matched by `ref_id`, not by array index: a store's `hits` mapper may legitimately drop an entry
@@ -7496,6 +7800,266 @@ function describe(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 //#endregion
+//#region ../core/lib/store/legs.js
+/**
+* The leg runner: how BOTH stores turn their own raw leg scores into `HybridLeg`s — plus the two
+* leg SOURCES that were the same flow twice ({@link ftsLeg}, {@link semanticLeg}, §4.6 of
+* `docs/vector-repair-shared-flow.md`). Both stores keep only their DAO/vstore primitives and their
+* scope: the `-rank`/`rank` sign convention, the short-query fallback, `max(50, k)`, the dimension
+* check's error and the Map insertion order live here once.
+*
+* `MemoryStore.searchLegs` and `KnowledgeStore.searchLegs` were the same skeleton written twice —
+* a `leg()` wrapper whose `capped` flag is measured on the RAW (pre-floor) score set, the
+* `applyTermFloor` / `applyScoreFloor` application, and the "semantic backend down ⇒ an EQUAL-WEIGHT
+* empty leg with `droppedByFloor: 0`" fallback — and even the comments explaining them were the same
+* paragraph twice. What legitimately differs is only the leg LIST and where each leg's scores come
+* from: memory computes anchors once and shares them between the entity and HRR legs, has the HRR
+* probe and the time-window scan; knowledge's entity leg is a query-driven async Jaccard. Those stay
+* at the store, exactly as §2 of `docs/vector-repair-shared-flow.md` requires.
+*
+* WHY THE CAP IS MEASURED ON THE RAW SET. `size === cap` is the only observable "this leg was cut"
+* signal (a leg that finished under the cap cannot have been trimmed), and it feeds the health
+* counters so the headroom can be sized from data — what makes the cap measurable instead of a silent
+* quality cliff (DESIGN §20.17). The relevance floors remove the tail anyway, so
+* deriving the flag from the FLOORED size would erase the signal exactly when the cap bound. The
+* floor functions only ever REMOVE entries, so the raw set is the honest measurement.
+*
+* WHY THE SEMANTIC LEG CARRIES NO `capped`. It is capped by the POOL size (`overFetch`), not by
+* `legCap`, so comparing it against `legCap` would report a trim that never happened. That is why
+* {@link LegRunner.semantic} is a separate method rather than a flag on {@link LegRunner.scored}:
+* the absence is structural, not something a caller can forget to set.
+*
+* WHY COMPOSITION. No base class (see the spec §2): the two stores share no construction, DB, DAO or
+* table, and a template-method base class would be a structural rewrite of two hub files. This is
+* the same style as `store/common.ts` — free functions plus a small interface — so a THIRD store can
+* be added by supplying its own leg list and sources and driving THIS runner (proved by a fake
+* third store in `test/legs.spec.ts`).
+*
+* CONCURRENCY lives one level up, in `store/hybrid.ts`'s `runLegs`: it awaits the returned
+* (value | promise) array concurrently and isolates a failing leg to itself. This module only BUILDS
+* legs, so both stores get the same awaiting and isolation by construction.
+*
+* @module store/legs
+*/
+/**
+* The one `capped` derivation (raw-set size vs cap). Kept as a named helper so the three call sites
+* cannot drift into measuring the floored set.
+*/
+function wasCapped(raw, cap) {
+	return raw.size === cap;
+}
+/**
+* Build the leg runner for one query.
+*
+* The per-store leg ORDER is NOT here: it is the store's "leg list" (see §4.5 阶段 4) because leg
+* index is part of the contract — `hybrid.ts`'s `unionLegs` merges the original and the
+* self-reference rewrite runs BY INDEX, so a store that reordered its legs would silently re-map
+* evidence. What this runner guarantees is that every leg, whichever order it lands in, gets the
+* same wrapper, the same floor order and the same down-semantic fallback.
+*/
+function makeLegRunner(ctx) {
+	const cap = ctx.legCap;
+	return {
+		cap,
+		plain(scores, weight) {
+			return {
+				weight,
+				scores,
+				capped: wasCapped(scores, cap)
+			};
+		},
+		scored(name, raw, weight, floor) {
+			const floored = applyScoreFloor(raw, floor);
+			return {
+				weight,
+				scores: floored.scores,
+				capped: wasCapped(raw, cap),
+				leg: name,
+				droppedByFloor: floored.dropped
+			};
+		},
+		term(name, raw, texts, query, weight, floor) {
+			const floored = applyTermFloor(raw, texts, query, floor);
+			return {
+				weight,
+				scores: floored.scores,
+				capped: wasCapped(raw, cap),
+				leg: name,
+				droppedByFloor: floored.dropped
+			};
+		},
+		semantic(raw, weight, floor) {
+			const floored = applyScoreFloor(raw, floor);
+			return {
+				weight,
+				scores: floored.scores,
+				leg: "semantic",
+				droppedByFloor: floored.dropped
+			};
+		},
+		semanticOff(weight) {
+			return {
+				weight,
+				scores: /* @__PURE__ */ new Map(),
+				leg: "semantic",
+				droppedByFloor: 0
+			};
+		}
+	};
+}
+/**
+* The FTS leg, shared by `MemoryStore.ftsPath` and `KnowledgeStore.ftsPath` (§4.6.1).
+*
+* The two were line-for-line the same flow — `buildFtsQuery` → the `MATCH` statement with NEGATED
+* bm25, else `substringTerms` → the LIKE statement with `rank` — differing only in the DAO and the
+* order its scope parameters bind. Both conventions are load-bearing and preserved verbatim:
+*
+*  - **bm25 is negative** (more negative = better match), so the `MATCH` branch negates it and higher
+*    stays better everywhere downstream;
+*  - **the LIKE `rank`** already counts contained terms, so it is used as-is, keeping the two branches
+*    on the same "higher = better" scale;
+*  - **an empty term list returns the empty map** (`substringTerms` yields none for a query with no
+*    3-char run) — the leg is empty by construction, not by a query that matched nothing.
+*
+* THE SHORT-QUERY FALLBACK. `buildFtsQuery` returning `null` means the query carries no term the
+* trigram index can express (measured: every term in the FTS table is 3 characters), which used to
+* leave this leg empty by construction — the 2-char CJK shape. `substringTerms` is the one finer
+* predicate the FTS5 trigram TABLE still answers (`LIKE '%…%'`), bounded by `cap`; the accuracy guard
+* is the per-row term floor in `applyTermFloor`, which requires the row to CONTAIN the run.
+*/
+function ftsLeg(opts) {
+	const ftsQuery = buildFtsQuery(opts.query, opts.tokenizer);
+	if (ftsQuery) {
+		const rows = opts.search(ftsQuery, opts.scope, opts.cap);
+		return new Map(rows.map((r) => [r.id, -r.rank]));
+	}
+	const terms = substringTerms(opts.query);
+	if (terms.length === 0) return /* @__PURE__ */ new Map();
+	const rows = opts.substringSearch(terms, opts.scope, opts.cap);
+	return new Map(rows.map((r) => [r.id, r.rank]));
+}
+/**
+* The semantic leg, shared by `MemoryStore.semanticPath` and `KnowledgeStore.semanticPath` (§4.6.2).
+*
+* The flow: encode (unless the caller supplied the vector) → dimension check → publish → over-fetch
+* `max(50, k)` from the vstore → empty pool early-returns → filter → map id→score. Both stores used
+* to spell all of it out; only the filter differs, and that difference lives in `filterTopk`.
+*
+* Preserved verbatim: the `max(50, k)` over-fetch (the pool must leave room for the filter to remove
+* rows without shrinking the leg below `k`), the `RetrievalInputError` and its exact message, the
+* empty-pool early return, and the returned map's insertion order (the vstore's pool order).
+*/
+async function semanticLeg(opts) {
+	const vec = opts.queryVector ?? await opts.encode(opts.query);
+	if (vec.length !== opts.dim) throw new RetrievalInputError(`queryVector 维度不符：${vec.length} != ${opts.dim}`);
+	opts.onVector?.(vec);
+	const topk = opts.topk(vec, Math.max(50, opts.k));
+	if (!topk.length) return /* @__PURE__ */ new Map();
+	const allowed = opts.filterTopk(topk.map((t) => t.id));
+	const out = /* @__PURE__ */ new Map();
+	for (const t of topk) if (allowed === void 0 || allowed.has(t.id)) out.set(t.id, t.score);
+	return out;
+}
+//#endregion
+//#region ../core/lib/store/entity_sweep.js
+/**
+* The ONE entity-version sweep both stores run.
+*
+* `entities_version` is the stamp that says "these entity rows were produced by the CURRENT
+* extraction rules". A rule change makes every row carrying an older stamp stale, and the only way
+* to close that gap is to re-extract those rows' text — for memory the entity links, the triples and
+* the HRR bundle derived from them; for knowledge the `chunk_entities` rows. That SKELETON was
+* written twice and drifted apart in exactly the ways a copy drifts: memory had the in-flight guard,
+* the budget clamp and the `{rebuilt, deferred, skipped}` report, while knowledge had the same
+* selection inlined in `reindex` with no guard at all. This module is the one copy; the stores
+* contribute a per-aggregate adapter (which rows, how to extract, what to write) and nothing else.
+*
+* Layering, deliberate: this is an ORCHESTRATION rule, not SQL, so it lives beside `common.ts` and
+* `legs.ts` in `store/` — the DAO layer stays split by aggregate and keeps its own statements
+* (`docs/vector-repair-shared-flow.md` §2 / §7).
+*
+* What must NOT move here: the extractor, the rows a store writes, and that store's side effects.
+* Memory's transaction also replaces triples, moves the HRR bundle and re-queues the conflict check
+* (both conflict legs read what the sweep rebuilt); knowledge replaces `chunk_entities` under
+* `MAX_ENTITIES_PER_CHUNK`. Those are domain semantics, and folding them in would trade one
+* duplicated loop for two conditional branches.
+*
+* @module store/entity_sweep
+*/
+/**
+* Rows one sweep pass may rebuild when the caller names no budget.
+*
+* `MemoryStore.reindexEntities` has always defaulted to this, and the CLI passes it explicitly; it
+* lives here so the shared loop and that public re-export cannot drift. Bounds MEMORY, not only
+* mission: a pass selects every chosen row's text before rebuilding the first one.
+*/
+const ENTITY_SWEEP_BATCH = 2e3;
+/**
+* The module-level in-flight guard.
+*
+* Held here, not in the stores, because it protects THIS loop: two callers can overlap (the plugin's
+* heartbeat and `maintenance` are both periodic), and a limited ORDERED selection makes two
+* concurrent passes pick the same rows and re-tag them twice. Overlap is not corruption — each row is
+* written in its own transaction — it is duplicated mission in a single-threaded process, and the
+* answer is one pass reporting `skipped`. A `WeakSet` keyed by the caller's guard object keeps the
+* state in this module without adding a mutable field to either hub store, and without a module-level
+* boolean that would make two stores' sweeps block each other.
+*
+* The `guard` argument is therefore an IDENTITY, not a token: a store must pass the SAME object to
+* every call for its whole lifetime (both stores hold one as a private field). Two different objects
+* are two different sweeps and run concurrently — that per-store granularity is the point.
+*/
+const SWEEPING = /* @__PURE__ */ new WeakSet();
+/**
+* Re-extract the entity rows written by older extraction rules, ONE bounded pass.
+*
+* The contract, in order: take the guard (an overlapping pass reports `skipped` and does nothing);
+* read the scope's stale count and at most `maxPerPass` rows; re-extract each row through the
+* adapter, isolating failures; report `{ rebuilt, deferred, skipped }`.
+*
+* Not an unbounded drain, on purpose: this is reachable from a settings-page button and a periodic
+* heartbeat, so it must not block on a whole stale corpus. Callers that want the corpus current loop
+* until `deferred === 0` (the CLI does).
+*
+* A row whose extraction or write throws is skipped, not fatal: the transaction that stamps the
+* version never ran, so the row is still stale and the NEXT pass retries it — the same retry contract
+* the knowledge store used per chunk. Letting the throw escape would instead abandon the rest of the
+* batch with no report of what was done.
+*
+* @param guard the store's stable in-flight identity (see {@link SWEEPING})
+*/
+async function sweepVersionedEntities(target, guard, opts = {}) {
+	const maxPerPass = Math.max(0, Math.floor(opts.budget ?? 2e3));
+	if (SWEEPING.has(guard)) return {
+		rebuilt: 0,
+		deferred: target.staleEntityCount?.() ?? target.staleEntityBatch(0).total,
+		skipped: true
+	};
+	SWEEPING.add(guard);
+	try {
+		const { total, rows } = target.staleEntityBatch(maxPerPass);
+		let rebuilt = 0;
+		for (const row of rows) {
+			if (opts.shouldStop?.() === true) break;
+			if (rebuilt >= maxPerPass) break;
+			try {
+				await target.extractAndWriteEntities(row);
+			} catch (error) {
+				target.onRowError(row, error);
+				continue;
+			}
+			rebuilt += 1;
+		}
+		return {
+			rebuilt,
+			deferred: Math.max(0, total - rebuilt),
+			skipped: false
+		};
+	} finally {
+		SWEEPING.delete(guard);
+	}
+}
+//#endregion
 //#region ../core/lib/db/vectors.js
 /** Little-endian Float32 ↔ BLOB helpers for persisted vectors (cross-platform stable). */
 function float32ToBytes(vec) {
@@ -7687,15 +8251,289 @@ async function forEachYielding(items, visit, every = 200) {
 		if ((index + 1) % every === 0) await yieldToEventLoop();
 	}
 }
-//#endregion
-//#region ../core/lib/store/secret_guard.js
 /**
-* Write-side secret / PII shape guard (P-03) — a PURE function, no store, no IO.
+* Rebuild one store's live vstore from its persisted rows, count what is unusable in the current
+* space, and say so once — the shared "open for business" step both stores used to write twice.
 *
-* The memory store is a long-lived, backed-up, sometimes-remote copy of what the model chose to
-* write down, so a plaintext credential that reaches it is hard to retract. This guard refuses a
-* fact whose TEXT matches a HIGH-CONFIDENCE credential/PII shape. It is deliberately narrow: only
-* shapes that a false positive is unlikely to produce, because a guard that refuses legitimate
+* The owning store's ONLY half is the row read (`facts.activeVectorRows()` /
+* `chunks.vectorRows()`); the reload, the count and the loud warning are one implementation, so a
+* change to what counts as stale cannot land on one store only (the incident this exists for: the
+* memory store checked the SPACE while knowledge checked only the WIDTH, so a model swap mixed two
+* spaces in one index until someone happened to run `kb_reindex`).
+*/
+function loadVectorIndex(opts) {
+	reloadVectorIndex(opts.vstore, opts.rows, opts.store);
+	const expectedBytes = opts.vstore.dim * 4;
+	let stale = 0;
+	let spaceStale = 0;
+	let legacy = 0;
+	for (const row of opts.rows) {
+		if (row.vec === null || row.vec.byteLength !== expectedBytes) {
+			stale++;
+			continue;
+		}
+		if (row.embedding_model !== opts.space) {
+			spaceStale++;
+			if (isPreFingerprintSpace(row.embedding_model)) legacy++;
+		}
+	}
+	reportStaleVectors(opts.store, opts.space, {
+		stale,
+		space_stale: spaceStale,
+		legacy
+	}, opts.manualEntry);
+	return {
+		stale,
+		space_stale: spaceStale,
+		legacy
+	};
+}
+/**
+* Encode rows one at a time, add each to the live index, and persist them in groups.
+*
+* The shared skeleton: serial encode (a MEASURED decision for chunks — a padded batched forward pass
+* is 1.79x slower on real 53–550 character chunks), `add` right after a successful encode, one
+* `write` call per `writeBatch` rows, per-row isolation of encode failures, per-group isolation of
+* write failures, and the `{ encoded, failed }` count.
+*
+* What stays with the store: the backend call, the live index, the write statement, the replay of a
+* failed group, and the summary log — the memory store logs per row and keeps a half-written index
+* (documented as the benign direction for it), the knowledge store evicts the group so both sides
+* agree that the vectors are missing.
+*/
+async function encodeAndPersist(rows, target) {
+	const every = Math.max(1, Math.floor(target.writeBatch ?? 1));
+	let encoded = 0;
+	let failed = 0;
+	for (let i = 0; i < rows.length; i += every) {
+		const group = rows.slice(i, i + every);
+		const writes = [];
+		for (const row of group) try {
+			const vec = await target.encode(row.text);
+			target.add(row.id, vec);
+			writes.push({
+				id: row.id,
+				bytes: float32ToBytes(vec)
+			});
+		} catch (error) {
+			failed += 1;
+			target.onRowError?.(row, error);
+		}
+		if (!writes.length) continue;
+		try {
+			target.write(writes);
+			encoded += writes.length;
+		} catch (error) {
+			failed += writes.length;
+			target.onWriteError?.(writes, error);
+		}
+	}
+	return {
+		encoded,
+		failed
+	};
+}
+/**
+* ONE bounded slice of the repair: re-add unusable-but-readable vectors that the live index lost,
+* drop the rows a re-encode has to replace, then encode up to `limit` missing/foreign rows.
+*
+* `limit` is what makes the SAME logic usable as a background migration: one call is a bounded unit
+* of work the caller can yield between. The explicit fix passes no limit (the operator action drains
+* everything); the background drive passes its batch size.
+*
+* The ORDER is an invariant: unusable bytes leave the table and the live index first, so a
+* re-encode can pick them up and a process that dies mid-migration leaves at most one batch
+* vector-less — exactly the `missing` rows the next run resumes on.
+*/
+async function repairVectorSlice(target, opts) {
+	const limit = opts.limit ?? Number.POSITIVE_INFINITY;
+	const c = target.classifyVectors(limit);
+	const loadedNow = target.semanticAvailable();
+	let semAvailable = loadedNow;
+	if (!semAvailable && !opts.dryRun && target.warmup !== void 0) semAvailable = await target.warmup();
+	const wouldWarm = !loadedNow;
+	const remainingOf = (encoded) => Math.max(0, c.stale + c.space_stale + c.missing - encoded);
+	const base = {
+		stale: c.stale,
+		space_stale: c.space_stale,
+		missing: c.missing,
+		semantic_available: semAvailable,
+		would_warm: wouldWarm
+	};
+	if (opts.dryRun) return {
+		report: {
+			...base,
+			...c.unindexed === void 0 ? {} : {
+				unindexed: c.unindexed.length,
+				reindexed: 0
+			},
+			dropped: 0,
+			encoded: 0,
+			failed: 0
+		},
+		remaining: remainingOf(0)
+	};
+	let reindexed = 0;
+	if (c.unindexed !== void 0) reindexed = target.reindexUsable?.(c.unindexed.slice(0, limit)) ?? 0;
+	let dropped = 0;
+	if (semAvailable && c.dropIds.length > 0) dropped = target.dropVectors(c.dropIds);
+	const { encoded, failed } = semAvailable ? await target.reencodeVectors(limit) : {
+		encoded: 0,
+		failed: 0
+	};
+	return {
+		report: {
+			...base,
+			...c.unindexed === void 0 ? {} : {
+				unindexed: c.unindexed.length,
+				reindexed
+			},
+			dropped,
+			encoded,
+			failed
+		},
+		remaining: remainingOf(encoded)
+	};
+}
+/**
+* ONE bounded slice of the background migration — the unit the drive (and the tests) step.
+*
+* Resumability is a property of the DATABASE, not of this process: every slice re-derives what is
+* stale from the persisted width/space, so a restart simply continues where the last slice stopped.
+*/
+async function migrateVectorSlice(target, batchSize = 16) {
+	const { report, remaining } = await repairVectorSlice(target, {
+		dryRun: false,
+		limit: Math.max(1, Math.floor(batchSize))
+	});
+	return {
+		remaining,
+		migrated: report.encoded,
+		dropped: report.dropped,
+		reindexed: report.reindexed ?? 0,
+		semantic_available: report.semantic_available
+	};
+}
+/** ACTIVE rows the semantic leg still cannot use (old width, old space, or no vector at all). */
+function migrationRemaining(target) {
+	const health = target.vectorSpaceHealth();
+	return health.stale + health.space_stale + target.missingVectorCount();
+}
+/** The `auto_migrate: false` warning is one per process per store, like the startup warning. */
+const disabledWarned = /* @__PURE__ */ new WeakSet();
+/**
+* Drive the bounded background migration for one store until it is current, the model is
+* unavailable, or `shouldStop()` turns true (plugin unmount / process shutdown). A batch FAILURE
+* never rejects: it is logged and reported as `remaining > 0`, which is what makes the next
+* heartbeat a retry. Never blocks the event loop for longer than one batch.
+*
+* Honours `semantic.auto_migrate` (default on) — the switch exists so a host that must not spend CPU
+* on background re-encoding can leave the loud warning and the manual entry as the only path. The
+* switch is read through the adapter so a new store cannot forget it.
+*/
+async function driveVectorRepair(target, opts = {}) {
+	const log = opts.log ?? retrievalLogger();
+	const stopped = () => opts.shouldStop?.() === true;
+	const enabled = target.autoMigrate() !== false;
+	const snapshot = () => ({
+		enabled,
+		remaining: migrationRemaining(target),
+		migrated: 0,
+		dropped: 0,
+		reindexed: 0,
+		semantic_available: target.semanticAvailable()
+	});
+	const initial = snapshot();
+	if (stopped()) return initial;
+	const health = target.vectorSpaceHealth();
+	const isSpaceChange = health.stale + health.space_stale > 0;
+	if (!enabled) {
+		if (initial.remaining > 0 && !disabledWarned.has(target)) {
+			disabledWarned.add(target);
+			log.warn(`${target.store} vector migration: ${String(initial.remaining)} ACTIVE vector(s) ${isSpaceChange ? "belong to an older embedding space" : "have no vector at all"} and \`semantic.auto_migrate\` is off — the semantic leg stays blind to them; run ${target.manualEntry} or set \`semantic.auto_migrate: true\``);
+		}
+		return initial;
+	}
+	if (initial.remaining === 0) return initial;
+	const startedAt = Date.now();
+	log.info(isSpaceChange ? `${target.store} vector migration: ${String(initial.remaining)} ACTIVE vector(s) belong to an older embedding space (${String(health.space_stale)} same-width, another representation, ${String(health.stale)} wrong-width) — re-encoding in the background (a representation change — model, pooling, normalization, input window or weights — migrates the whole corpus once)` : `${target.store} vector migration: ${String(initial.remaining)} ACTIVE row(s) have no vector at all — encoding them in the background`);
+	let migrated = 0;
+	let dropped = 0;
+	let reindexed = 0;
+	let last = initial;
+	for (;;) {
+		if (stopped()) break;
+		let step;
+		try {
+			step = await migrateVectorSlice(target, opts.batchSize);
+		} catch (error) {
+			log.warn(`${target.store} vector migration: batch failed (${describeError$2(error)}) — ${String(migrationRemaining(target))} vector(s) still cannot be used by the semantic leg; the next pass retries`);
+			break;
+		}
+		migrated += step.migrated;
+		dropped += step.dropped;
+		reindexed += step.reindexed;
+		last = {
+			...step,
+			enabled,
+			migrated,
+			dropped,
+			reindexed
+		};
+		opts.onProgress?.(last);
+		log.info(`${target.store} vector migration: re-encoded ${String(migrated)}/${String(initial.remaining)} (${String(step.remaining)} left)`);
+		if (step.migrated === 0 && step.dropped === 0 && step.reindexed === 0) break;
+		if (last.remaining === 0) break;
+		await yieldToEventLoop();
+	}
+	if (last.remaining === 0) log.info(`${target.store} vector migration: complete — ${String(migrated)} vector(s) re-encoded in ${String(Date.now() - startedAt)}ms; the semantic leg is current`);
+	else if (!stopped()) log.warn(`${target.store} vector migration: ${String(last.remaining)} vector(s) still cannot be used by the semantic leg (the embedding model may be unavailable) — the next heartbeat retries; manual entry ${target.manualEntry}`);
+	return last;
+}
+/**
+* Drive every store in order. A stop request keeps the drive from starting another store, but each
+* store still answers with its snapshot (so the caller can report what is left everywhere).
+*/
+async function driveVectorRepairs(targets, opts = {}) {
+	const outcomes = [];
+	for (const target of targets) outcomes.push(await driveVectorRepair(target, opts));
+	return outcomes;
+}
+/**
+* The explicit, unbounded repair behind `mem_admin vectors_fix` / `avantf-mem vectors --fix`,
+* covering one or both stores.
+*
+* `store` selects a single store (omitted = both); `dry_run` previews every count without writing —
+* and without loading the model (so a preview also reports `would_warm`). The top-level
+* `semantic_available` is AND over the selected stores: `false` means at least one store's repair
+* could not encode anything.
+*/
+async function vectorsFix(targets, opts) {
+	const stores = {};
+	let semanticAvailable = true;
+	for (const kind of ["memory", "knowledge"]) {
+		if (opts.store !== void 0 && opts.store !== kind) continue;
+		const target = targets[kind];
+		if (target === void 0) continue;
+		const { report } = await repairVectorSlice(target, { dryRun: opts.dryRun });
+		stores[kind] = report;
+		semanticAvailable = semanticAvailable && report.semantic_available;
+	}
+	return {
+		stores,
+		semantic_available: semanticAvailable,
+		dry_run: opts.dryRun
+	};
+}
+//#endregion
+//#region ../core/lib/store/secret_guard.js
+/**
+* Write-side secret / PII shape guard (P-03) — a PURE function, no store, no IO.
+*
+* The memory store is a long-lived, backed-up, sometimes-remote copy of what the model chose to
+* write down, so a plaintext credential that reaches it is hard to retract. This guard refuses a
+* fact whose TEXT matches a HIGH-CONFIDENCE credential/PII shape. It is deliberately narrow: only
+* shapes that a false positive is unlikely to produce, because a guard that refuses legitimate
 * notes is worse than no guard — the model learns to stop recording.
 *
 * What it does NOT do, by design:
@@ -8460,6 +9298,124 @@ function inList(values) {
 	};
 }
 //#endregion
+//#region ../core/lib/db/dao/shared.js
+/**
+* The entity-candidate leg's ORDER contract — the tail every candidate statement ends with.
+*
+* The formula is the leg's own score (anchored Jaccard with a saturating union,
+* `store/entity_leg.ts`): `shared / (queryWidth + min(total - shared, widthCap))`. Ordering by it is
+* load-bearing, not cosmetic: `fuse` scales each leg by its maximum, and a survivor's scaled value
+* is unchanged only when the ordering — and therefore the maximum — survives the trim. A narrower
+* row sharing one entity can therefore outrank a wide one sharing two, and the cap keeps it.
+* `total ASC` is only a deterministic tie-break among equal ratios, and the id makes the order total.
+*
+* `idColumn` is the aggregate's own id (`fa.fact_id` / `ce.chunk_id`); that, the `total` subquery's
+* table and the filter predicates are the ONLY differences between the two statements.
+*/
+function entityCandidateTail(idColumn) {
+	return `GROUP BY ${idColumn}
+  ORDER BY (CAST(shared AS REAL) / (? + MIN(total - shared, ?))) DESC, total ASC, ${idColumn} ASC
+  LIMIT ?`;
+}
+/**
+* Run an entity-candidate query: bind order, batching and union are shared; the SQL is the caller's.
+*
+* Bind order (identical in both aggregates): `<names …>, <filterParams …>, queryWidth, widthCap, limit`.
+*/
+function entityCandidates(db, q) {
+	if (!q.names.length || q.limit <= 0) return [];
+	const out = [];
+	const seen = q.batchNames ? /* @__PURE__ */ new Set() : null;
+	for (const batch of q.batchNames ? batches(q.names) : [q.names]) {
+		const { placeholders, values } = inList(batch);
+		const rows = db.prepare(q.sql(placeholders)).all(...values, ...q.filterParams, q.queryWidth, q.widthCap, q.limit);
+		for (const row of rows) {
+			if (seen !== null) {
+				if (seen.has(row.id)) continue;
+				seen.add(row.id);
+			}
+			out.push(row.id);
+		}
+	}
+	return out;
+}
+/**
+* The batched `UPDATE … SET entities_version = ?` shared by `FactsDao` and `ChunksDao`.
+*
+* Only the aggregate's `table` / `idColumn` differ. Returns the summed `changes`; the knowledge
+* caller ignores it (its method's signature returns `void`), the memory caller's `number` is
+* unchanged.
+*/
+function setEntitiesVersionBatch(db, table, idColumn, ids, version) {
+	let changes = 0;
+	for (const batch of batches(ids)) {
+		const { placeholders, values } = inList(batch);
+		changes += db.prepare(`UPDATE ${table} SET entities_version = ? WHERE ${idColumn} IN (${placeholders})`).run(version, ...values).changes;
+	}
+	return changes;
+}
+/**
+* Document frequency — "how many rows carry each name".
+*
+* Shared by `EntitiesDao.activeDocFrequency` and `ChunksDao.docFrequency`; the only difference is
+* the population the caller's `where`/`from` describe (memory counts ACTIVE facts, knowledge has no
+* status column and counts chunks). Only the caller's QUERY names are looked up, so this is one
+* indexed COUNT per name rather than a corpus scan. A name absent from the map has frequency 0.
+*/
+function queryDocFrequency(db, names, q) {
+	const out = /* @__PURE__ */ new Map();
+	if (!names.length) return out;
+	const { placeholders, values } = inList(names);
+	const rows = db.prepare(`SELECT ${q.nameExpr} AS name, COUNT(*) AS df${q.from}
+        WHERE ${q.nameExpr} IN (${placeholders})${q.where === void 0 ? "" : ` AND ${q.where}`}
+        GROUP BY ${q.nameExpr}`).all(...values);
+	for (const row of rows) out.set(row.name, Number(row.df));
+	return out;
+}
+/**
+* The SHORT-QUERY LIKE fallback shared by `FactsDao.ftsSubstringSearch` and
+* `ChunksDao.ftsSubstringSearch`.
+*
+* The predicate text itself already comes from `db/tokenizer.ts#likeSubstring`; this owns the
+* protocol AROUND it, which both copies spelled out:
+*
+*  1. build the fragments — empty terms yield no patterns, which means "match nothing" ⇒ `[]`;
+*  2. `count` lands in the SELECT and `any` in the WHERE, so the SAME pattern list is bound TWICE:
+*     once with the SELECT's placeholders, then — after the caller's filter params — with the
+*     WHERE's;
+*  3. `LIMIT ?` last, defaulting to `-1` (unbounded; the store bounds the leg).
+*
+* `ORDER BY rank DESC, <id> ASC` stays in the caller's SQL: the id column is aggregate-specific and
+* `rank` must read the SELECT alias, so the fragments and the patterns are built once and used twice.
+*/
+function likeSubstringLeg(db, column, terms, buildSql, filterParams = [], limit) {
+	const fragments = likeSubstring(column, terms);
+	if (fragments.params.length === 0) return [];
+	return db.prepare(buildSql(fragments)).all(...fragments.params, ...filterParams, ...fragments.params, limit ?? -1);
+}
+/**
+* Batched entity-name bags for a row-id set: `Map<rowId, names>`.
+*
+* Shared by `EntitiesDao.bagsForFacts` and `ChunksDao.entityBags` (§4.6.3): one `IN (…)` statement
+* per `batches()` slice, rows folded into the map in first-seen order. The SQL SHAPE is the only
+* aggregate-specific part (`table` / `keyColumn` / `nameColumn` / `joinEntities`); the crucial
+* `seedEmpty` difference above is the caller's to declare and stays observable.
+*/
+function entityBags(db, ids, q) {
+	const out = /* @__PURE__ */ new Map();
+	if (q.seedEmpty) for (const id of ids) out.set(id, []);
+	for (const batch of batches(ids)) {
+		const { placeholders, values } = inList(batch);
+		const rows = db.prepare(`SELECT ${q.keyColumn} AS id, ${q.nameColumn} AS name FROM ${q.table}${q.joinEntities === void 0 ? "" : ` ${q.joinEntities}`} WHERE ${q.keyColumn} IN (${placeholders})`).all(...values);
+		for (const row of rows) {
+			const list = out.get(row.id);
+			if (list) list.push(row.name);
+			else out.set(row.id, [row.name]);
+		}
+	}
+	return out;
+}
+//#endregion
 //#region ../core/lib/db/dao/entities.js
 var EntitiesDao = class {
 	db;
@@ -8506,17 +9462,13 @@ var EntitiesDao = class {
 	}
 	/** Batched entity bags for a candidate set: `Map<factId, names>` (ids with none get `[]`). */
 	bagsForFacts(ids) {
-		const out = /* @__PURE__ */ new Map();
-		if (!ids.length) return out;
-		for (const id of ids) out.set(id, []);
-		for (const batch of batches(ids)) {
-			const { placeholders, values } = inList(batch);
-			const rows = this.db.prepare(`SELECT fe.fact_id AS fact_id, e.name AS name FROM fact_entities fe
-           JOIN entities e ON e.entity_id = fe.entity_id
-           WHERE fe.fact_id IN (${placeholders})`).all(...values);
-			for (const row of rows) out.get(row.fact_id)?.push(row.name);
-		}
-		return out;
+		return entityBags(this.db, ids, {
+			table: "fact_entities fe",
+			keyColumn: "fe.fact_id",
+			nameColumn: "e.name",
+			joinEntities: "JOIN entities e ON e.entity_id = fe.entity_id",
+			seedEmpty: true
+		});
 	}
 	/** How many entities a fact is linked to — the scorer's `|A|`. */
 	countForFact(factId) {
@@ -8533,17 +9485,14 @@ var EntitiesDao = class {
 	* map has frequency 0, i.e. no active fact carries it and it can never be shared.
 	*/
 	activeDocFrequency(names) {
-		const out = /* @__PURE__ */ new Map();
-		if (!names.length) return out;
-		const { placeholders, values } = inList(names);
-		const rows = this.db.prepare(`SELECT e.name AS name, COUNT(*) AS df
+		return queryDocFrequency(this.db, names, {
+			from: `
            FROM entities e
            JOIN fact_entities fe ON fe.entity_id = e.entity_id
-           JOIN facts fa ON fa.fact_id = fe.fact_id
-          WHERE e.name IN (${placeholders}) AND fa.status = 'active'
-          GROUP BY e.name`).all(...values);
-		for (const row of rows) out.set(row.name, Number(row.df));
-		return out;
+           JOIN facts fa ON fa.fact_id = fe.fact_id`,
+			nameExpr: "e.name",
+			where: "fa.status = 'active'"
+		});
 	}
 	/**
 	* Candidate facts for the embedding leg, narrowed by the scorer's NECESSARY conditions
@@ -8602,9 +9551,19 @@ var EntitiesDao = class {
 	* survivors, so one formula stays in charge.
 	*/
 	candidateFactsForAnyEntity(names, category, limit, queryWidth, widthCap, source) {
-		if (!names.length || limit <= 0) return [];
-		const { placeholders, values } = inList(names);
-		return this.db.prepare(`SELECT fa.fact_id AS id, COUNT(*) AS shared,
+		return entityCandidates(this.db, {
+			names,
+			filterParams: [
+				category ?? null,
+				category ?? null,
+				source ?? null,
+				source ?? null
+			],
+			limit,
+			queryWidth,
+			widthCap,
+			batchNames: false,
+			sql: (placeholders) => `SELECT fa.fact_id AS id, COUNT(*) AS shared,
                 (SELECT COUNT(*) FROM fact_entities x WHERE x.fact_id = fa.fact_id) AS total
            FROM facts fa
            JOIN fact_entities fe ON fe.fact_id = fa.fact_id
@@ -8613,9 +9572,8 @@ var EntitiesDao = class {
             AND (? IS NULL OR EXISTS (
                   SELECT 1 FROM fact_sources fs WHERE fs.fact_id = fa.fact_id AND fs.ref = ?
                 ))
-          GROUP BY fa.fact_id
-          ORDER BY (CAST(shared AS REAL) / (? + MIN(total - shared, ?))) DESC, total ASC, fa.fact_id ASC
-          LIMIT ?`).all(...values, category ?? null, category ?? null, source ?? null, source ?? null, queryWidth, widthCap, limit).map((row) => row.id);
+          ${entityCandidateTail("fa.fact_id")}`
+		});
 	}
 };
 //#endregion
@@ -8967,12 +9925,7 @@ var FactsDao = class FactsDao {
 	}
 	/** Stamp the rules that produced a batch of rows' entity/triple data. */
 	setEntitiesVersion(ids, version) {
-		let changes = 0;
-		for (const batch of batches(ids)) {
-			const { placeholders, values } = inList(batch);
-			changes += this.db.prepare(`UPDATE facts SET entities_version = ? WHERE fact_id IN (${placeholders})`).run(version, ...values).changes;
-		}
-		return changes;
+		return setEntitiesVersionBatch(this.db, "facts", "fact_id", ids, version);
 	}
 	/**
 	* Replace a fact's HRR vector.
@@ -9352,14 +10305,16 @@ var FactsDao = class FactsDao {
 	* alias, so the LIKE expressions are built once and bound twice — same fragment, same order.
 	*/
 	ftsSubstringSearch(terms, category, limit, source) {
-		const { any, count, params } = likeSubstring("fa.content", terms);
-		if (params.length === 0) return [];
 		const sourceClause = source === void 0 ? "" : " AND EXISTS (SELECT 1 FROM fact_sources fs WHERE fs.fact_id = fa.fact_id AND fs.ref = ?)";
-		return this.db.prepare(`SELECT fa.fact_id AS id, ${count} AS rank
+		return likeSubstringLeg(this.db, "fa.content", terms, ({ any, count }) => `SELECT fa.fact_id AS id, ${count} AS rank
            FROM facts fa
           WHERE fa.status = 'active' AND (? IS NULL OR fa.category = ?)${sourceClause} AND (${any})
           ORDER BY rank DESC, fa.fact_id ASC
-          LIMIT ?`).all(...params, category ?? null, category ?? null, ...source === void 0 ? [] : [source], ...params, limit ?? -1);
+          LIMIT ?`, source === void 0 ? [category ?? null, category ?? null] : [
+			category ?? null,
+			category ?? null,
+			source
+		], limit);
 	}
 	/**
 	* ①'s predicate: the active-day counter crossed an integer boundary since the last settle.
@@ -10441,15 +11396,6 @@ const NO_CHECK = {
 	complete: false
 };
 /**
-* Facts one derived-state sweep pass may rebuild (`reindexEntities`'s default budget).
-*
-* Bounds MEMORY, not only mission: the pass selects `content` for every row it takes, so an
-* "unbounded" pass (the CLI used to ask for `Number.MAX_SAFE_INTEGER`) builds an array of every
-* stale fact's text before rebuilding the first one. Callers that want the corpus drained loop
-* until `deferred === 0` instead.
-*/
-const ENTITY_SWEEP_BATCH = 2e3;
-/**
 * `avantf_stats` key holding the retrieval-health snapshot.
 *
 * The counters are process-wide, but the MEMORY store owns the side table, so it is the single
@@ -10495,8 +11441,14 @@ var MemoryStore = class {
 	* and building MATCH expressions for the wrong one is silent zero recall (see `db/tokenizer.ts`).
 	*/
 	ftsTokenizer;
-	/** In-flight guard for `reindexEntities` (see there: the periodic callers can overlap). */
-	entitySweepInFlight = false;
+	/**
+	* Identity object for the shared entity sweep's in-flight guard (`store/entity_sweep.ts`).
+	*
+	* The guard itself lives in that module; this is only the per-store identity it keys on. It keeps
+	* the rule where the loop is (the periodic callers can overlap), without a mutable field that two
+	* stores would each have to remember to hold.
+	*/
+	entitySweepGuard = {};
 	/**
 	* Where the next conflict drain resumes (see `checkContradictions`). A scheduling cursor, not
 	* derived state: nothing is lost when it resets, and the queue itself is in the database.
@@ -10536,7 +11488,7 @@ var MemoryStore = class {
 			clock,
 			budget: opts?.budget ?? trust.tick_max_facts
 		});
-		this.evictVectors([...result.archived_ids, ...result.purged_ids]);
+		evictVectors(this.vstore, [...result.archived_ids, ...result.purged_ids]);
 		this.retireConflicts([...result.archived_ids, ...result.purged_ids]);
 		this.db.pragma("optimize");
 		return result;
@@ -10550,22 +11502,32 @@ var MemoryStore = class {
 		return vectorSpaceOf(this.semantic, this.config.semantic.local_model);
 	}
 	/**
-	* Rebuild the in-memory vstore from persisted `facts.semantic_vector` BLOBs.
-	* Without this the semantic path is silently empty after every process restart
-	* (the DB is the authoritative vector store; the vstore is a derived read model).
+	* Rebuild the in-memory vstore from persisted `facts.semantic_vector` BLOBs, and say loudly what
+	* belongs to another vector space.
 	*
-	* Only ACTIVE facts are indexed: archived facts are filtered out of every
-	* retrieval path anyway, so loading them would only grow the index forever.
-	* `archive()` evicts and `restore()` re-adds, keeping the invariant.
+	* Without this the semantic path is silently empty after every process restart (the DB is the
+	* authoritative vector store; the vstore is a derived read model). Only ACTIVE facts are indexed:
+	* archived facts are filtered out of every retrieval path anyway, so loading them would only grow
+	* the index forever — `archive()` evicts and `restore()` re-adds, keeping the invariant.
+	*
+	* The reload, the `{ stale, space_stale, legacy }` count and the warning are the SHARED open-time
+	* step (`store/vector_repair.ts`); this store's half is the row read. A dim-valid vector from
+	* another space is still RANKED (the reload cannot tell the difference), so a silent model swap
+	* would mix two spaces in one index — acting on it is the manual fix's job for the operator path
+	* and the bounded background migration's for the automatic one.
 	*/
 	reloadIndex() {
-		const space = this.vectorSpace();
-		const rows = this.facts.activeVectorRows().map((r) => ({
-			id: r.fact_id,
-			vec: r.semantic_vector
-		}));
-		reloadVectorIndex(this.vstore, rows, "memory");
-		reportStaleVectors("memory", space, this.vectorSpaceCounts(), "`avantf-mem vectors --fix` (MCP/plugin: `mem_admin vectors_fix`)");
+		loadVectorIndex({
+			store: "memory",
+			vstore: this.vstore,
+			rows: this.facts.activeVectorRows().map((r) => ({
+				id: r.fact_id,
+				vec: r.semantic_vector,
+				embedding_model: r.embedding_model
+			})),
+			space: this.vectorSpace(),
+			manualEntry: "`avantf-mem vectors --fix` (MCP/plugin: `mem_admin vectors_fix`)"
+		});
 	}
 	/**
 	* Cheapest possible DETECTION of "the embedding space changed under this store": counts of ACTIVE
@@ -10666,21 +11628,45 @@ var MemoryStore = class {
 			};
 		}
 	}
+	/**
+	* This store's half of the shared encode-and-persist flow (`store/vector_repair.ts`): the backend
+	* call, the live index and the single-row write. The write records the VECTOR SPACE, not just the
+	* backend name — a same-width model swap is otherwise indistinguishable from "already encoded"
+	* (DESIGN §20) — and `setSemanticVector` re-queues the fact for the conflict check.
+	*/
+	vectorWriteTarget(space) {
+		return {
+			store: "memory",
+			space,
+			encode: (text) => this.semantic.encode(text),
+			add: (id, vec) => {
+				this.vstore.add(id, vec);
+			},
+			write: (rows) => {
+				for (const r of rows) this.facts.setSemanticVector(r.id, r.bytes, space, this.vstore.name);
+			},
+			onRowError: (row, error) => {
+				this.warnIndexFailure(row.id, error);
+			},
+			onWriteError: (rows, error) => {
+				for (const r of rows) this.warnIndexFailure(r.id, error);
+			}
+		};
+	}
+	warnIndexFailure(factId, error) {
+		retrievalLogger().warn(`memory index: fact ${String(factId)} was not semantically indexed (${describeError$2(error)}) — run mem_admin vectors_diagnose to see the shortfall, vectors_fix to re-encode`);
+	}
 	/** Best-effort semantic indexing: encode the fact and add it to the vstore. */
 	async maybeIndexSemantic(factId, content) {
-		try {
-			if (!this.semantic.isAvailable()) {
-				this.semantic.ensureWarm?.();
-				return false;
-			}
-			const vec = await this.semantic.encode(content);
-			this.vstore.add(factId, vec);
-			this.facts.setSemanticVector(factId, float32ToBytes(vec), this.vectorSpace(), this.vstore.name);
-			return true;
-		} catch (error) {
-			retrievalLogger().warn(`memory index: fact ${String(factId)} was not semantically indexed (${describeError$2(error)}) — run mem_admin vectors_diagnose to see the shortfall, vectors_fix to re-encode`);
+		if (!this.semantic.isAvailable()) {
+			this.semantic.ensureWarm?.();
 			return false;
 		}
+		const { encoded } = await encodeAndPersist([{
+			id: factId,
+			text: content
+		}], this.vectorWriteTarget(this.vectorSpace()));
+		return encoded === 1;
 	}
 	async update(fact_id, content, category, ttlDays, opts) {
 		if (!this.getRow(fact_id)) throw new Error(`找不到 fact_id=${fact_id}`);
@@ -10775,7 +11761,7 @@ var MemoryStore = class {
 			this.facts.reinforceOutcome(fact_id, outcome.next, clock, outcome.bonusCount, outcome.windowAt);
 			return null;
 		}).immediate();
-		if (evict !== null) this.evictVectors([evict]);
+		if (evict !== null) evictVectors(this.vstore, [evict]);
 		return this.getRow(fact_id)?.helpful_count ?? 0;
 	}
 	/** Permanent-memory administration (spec §6). */
@@ -11070,168 +12056,103 @@ var MemoryStore = class {
 		};
 	}
 	/**
-	* Repair the semantic read model, in ONE bounded slice or in full:
-	*  (a) reload persisted, dim-valid vectors missing from the live index
-	*      (restart / index loss — needs no model),
-	*  (b) drop persisted vectors whose dim no longer matches `semantic.dim` so a
-	*      re-encode can replace them (never `add()` a stale vector — the store
-	*      throws on dim mismatch),
-	*  (c) encode active facts that have no vector yet (needs the semantic backend),
-	*  (d) re-encode vectors written in ANOTHER vector space (a model swap, or the one-time
-	*      adoption of a store predating the space id).
-	*
-	* `limit` is what makes the SAME logic usable as a background migration: at most that many rows are
-	* dropped and at most that many are re-encoded, so one call is a bounded unit of work the caller can
-	* yield between. `vectorsFix` passes no limit (the explicit operator action drains everything);
-	* `migrateVectorsBatch` passes the migration's batch size.
+	* This store's half of the shared repair flow (`store/vector_repair.ts`): the primitives the flow
+	* steps. The flow itself — batch size, event-loop yield, stop / resume / no-progress rules,
+	* `semantic.auto_migrate`, the dry-run split and the drop-before-encode order — lives there once,
+	* for both stores.
 	*/
-	async repairVectors(opts) {
-		const limit = opts.limit ?? Number.POSITIVE_INFINITY;
-		const c = this.classifyVectors();
-		const loadedNow = this.semantic.isAvailable();
-		let semAvailable = loadedNow;
-		if (!semAvailable && !opts.dryRun) semAvailable = await this.warmupSemantic();
-		const wouldWarm = !loadedNow;
-		const remainingOf = (fixed) => Math.max(0, c.staleIds.length + c.spaceStaleIds.length + c.missing - fixed);
-		if (opts.dryRun) return {
-			report: {
-				missing: c.missing,
-				stale: c.staleIds.length,
-				space_stale: c.spaceStaleIds.length,
-				unindexed: c.unindexed.length,
-				reindexed: 0,
-				dropped: 0,
-				fixed: 0,
-				semantic_available: semAvailable,
-				would_warm: wouldWarm,
-				dry_run: true
-			},
-			remaining: remainingOf(0)
+	vectorRepairTarget() {
+		return {
+			store: "memory",
+			manualEntry: "`avantf-mem vectors --fix` (MCP/plugin: `mem_admin vectors_fix`)",
+			vectorSpace: () => this.vectorSpace(),
+			semanticAvailable: () => this.semantic.isAvailable(),
+			autoMigrate: () => this.config.semantic.auto_migrate,
+			vectorSpaceHealth: () => this.vectorSpaceHealth(),
+			missingVectorCount: () => this.facts.vectorCounts().missing,
+			classifyVectors: (limit) => this.classifyRepairVectors(limit),
+			reindexUsable: (rows) => this.reindexUsableVectors(rows),
+			dropVectors: (ids) => this.dropRepairVectors(ids),
+			reencodeVectors: (limit) => this.reencodeMissingVectors(limit),
+			warmup: () => this.warmupSemantic()
 		};
-		let reindexed = 0;
-		for (const u of c.unindexed.slice(0, limit)) {
-			this.vstore.add(u.id, u.vec);
-			reindexed++;
-		}
-		let dropped = 0;
-		if (semAvailable) {
-			const toDrop = [...c.staleIds, ...c.spaceStaleIds].slice(0, limit);
-			if (toDrop.length) {
-				const spaceStale = new Set(c.spaceStaleIds);
-				dropped = this.facts.clearVectors(toDrop);
-				this.evictVectors(toDrop.filter((id) => spaceStale.has(id)));
-			}
-		}
-		let fixed = 0;
-		if (semAvailable) {
-			const missingRows = this.facts.missingVectorRows().slice(0, limit);
-			for (const m of missingRows) {
-				if (!await this.maybeIndexSemantic(m.fact_id, m.content)) continue;
-				fixed++;
-			}
-		}
+	}
+	/**
+	* {@link classifyVectors} reduced to what the repair flow steps on: the counts, the ids to drop
+	* (bounded by `limit`) and the decoded vectors that can go back into a lost live index.
+	*/
+	classifyRepairVectors(limit) {
+		const c = this.classifyVectors();
 		return {
-			report: {
-				missing: c.missing,
-				stale: c.staleIds.length,
-				space_stale: c.spaceStaleIds.length,
-				unindexed: c.unindexed.length,
-				reindexed,
-				dropped,
-				fixed,
-				semantic_available: semAvailable,
-				would_warm: wouldWarm,
-				dry_run: false
-			},
-			remaining: remainingOf(fixed)
+			stale: c.staleIds.length,
+			space_stale: c.spaceStaleIds.length,
+			missing: c.missing,
+			dropIds: [...c.staleIds, ...c.spaceStaleIds].slice(0, limit),
+			unindexed: c.unindexed
+		};
+	}
+	/** Put usable persisted vectors missing from the live index back into it (no model needed). */
+	reindexUsableVectors(rows) {
+		for (const u of rows) this.vstore.add(u.id, u.vec);
+		return rows.length;
+	}
+	/**
+	* Unusable bytes (dim mismatch) and foreign-space vectors both have to go before a re-encode can
+	* pick them up, and for the same reason: `add()` would keep ranking them otherwise. Only the slice
+	* the flow is about to re-encode is passed in, so a process that dies mid-migration leaves at most
+	* one batch vector-less — those rows are exactly the `missing` rows the next run resumes on.
+	*
+	* `clearVectors` re-queues each fact for the conflict check (`conflict_checked = 0`): the vector
+	* the embedding leg was checked against is gone, so the check has to run again.
+	*/
+	dropRepairVectors(ids) {
+		if (!ids.length) return 0;
+		const dropped = this.facts.clearVectors(ids);
+		evictVectors(this.vstore, ids);
+		return dropped;
+	}
+	/**
+	* Encode the ACTIVE facts that still have no vector in this space (needs the semantic backend).
+	*
+	* Every row lands through `setSemanticVector`, which re-queues the fact for the conflict check —
+	* the same rule as {@link dropRepairVectors}: a fact whose vector the leg could not see when it
+	* ran has not been checked.
+	*/
+	async reencodeMissingVectors(limit) {
+		const rows = this.facts.missingVectorRows().slice(0, limit).map((m) => ({
+			id: m.fact_id,
+			text: m.content
+		}));
+		if (!rows.length) return {
+			encoded: 0,
+			failed: 0
 		};
+		return await encodeAndPersist(rows, this.vectorWriteTarget(this.vectorSpace()));
 	}
 	/**
 	* The explicit, unbounded repair behind `mem_admin vectors_fix` / `avantf-mem vectors --fix`.
 	* `dry_run` previews every count without writing — and without loading the model, which is why
-	* the preview also reports `would_warm` (see the contract's `VectorsFixReport`).
+	* the preview also reports `would_warm` (see the contract's `VectorsFixStoreReport`).
 	*/
 	async vectorsFix(dryRun = false) {
-		return (await this.repairVectors({ dryRun })).report;
+		return (await repairVectorSlice(this.vectorRepairTarget(), { dryRun })).report;
 	}
 	/**
 	* ONE bounded slice of the vector-space migration: at most `batchSize` rows are dropped and
 	* re-encoded, so the caller keeps control of the event loop between slices. This is the unit the
 	* background migration ({@link migrateVectors}) and its tests drive.
-	*
-	* Resumability is a property of the DATABASE, not of this process: every slice re-derives what is
-	* stale from the persisted width/space, so a restart simply continues where the last slice stopped.
 	*/
 	async migrateVectorsBatch(batchSize = 16) {
-		const size = Math.max(1, Math.floor(batchSize));
-		const { report, remaining } = await this.repairVectors({
-			dryRun: false,
-			limit: size
-		});
-		return {
-			remaining,
-			migrated: report.fixed,
-			dropped: report.dropped,
-			reindexed: report.reindexed,
-			semantic_available: report.semantic_available
-		};
+		return await migrateVectorSlice(this.vectorRepairTarget(), batchSize);
 	}
 	/**
 	* Drive the bounded background migration until the store is current, the model is unavailable, or
-	* `shouldStop()` turns true (plugin unmount / process shutdown). A batch FAILURE never rejects: it is
-	* logged and reported as `remaining > 0`, which is what makes the next heartbeat a retry (the caller
-	* still owns the outer catch for a closed database, e.g. a shutdown racing the first read). Never
-	* blocks the event loop for longer than one batch.
-	*
-	* Honours `semantic.auto_migrate` (default on) — the switch exists so a host that must not spend CPU
-	* on background re-encoding can leave the loud warning and the manual entry as the only path.
+	* `shouldStop()` turns true (plugin unmount / process shutdown). The loop, the `semantic.auto_migrate`
+	* switch, the no-progress rule and the store-named logging all live in the shared flow
+	* (`store/vector_repair.ts`); this is the one-store entry callers (and its tests) already use.
 	*/
 	async migrateVectors(opts = {}) {
-		const enabled = this.config.semantic.auto_migrate !== false;
-		const snapshot = () => ({
-			enabled,
-			remaining: this.migrationRemaining(),
-			migrated: 0,
-			dropped: 0,
-			reindexed: 0,
-			semantic_available: this.semantic.isAvailable()
-		});
-		if (!enabled) return snapshot();
-		let migrated = 0;
-		let dropped = 0;
-		let reindexed = 0;
-		let last = snapshot();
-		if (last.remaining === 0) return last;
-		for (;;) {
-			if (opts.shouldStop?.() === true) break;
-			let step;
-			try {
-				step = await this.migrateVectorsBatch(opts.batchSize);
-			} catch (error) {
-				retrievalLogger().warn(`memory vector migration: batch failed (${describeError$2(error)}) — ${String(this.migrationRemaining())} vector(s) still belong to an older embedding space; the next pass retries`);
-				break;
-			}
-			migrated += step.migrated;
-			dropped += step.dropped;
-			reindexed += step.reindexed;
-			last = {
-				...step,
-				enabled,
-				migrated,
-				dropped,
-				reindexed
-			};
-			opts.onProgress?.(last);
-			if (step.migrated === 0 && step.dropped === 0 && step.reindexed === 0) break;
-			if (last.remaining === 0) break;
-			await yieldToEventLoop();
-		}
-		return last;
-	}
-	/** Active rows the semantic leg still cannot use (old width, old space, or no vector at all). */
-	migrationRemaining() {
-		const health = this.vectorSpaceHealth();
-		return health.stale + health.space_stale + this.facts.vectorCounts().missing;
+		return await driveVectorRepair(this.vectorRepairTarget(), opts);
 	}
 	/**
 	* One lifecycle pass, owned by the store so the DB writes and the live-index
@@ -11246,7 +12167,7 @@ var MemoryStore = class {
 	*/
 	async maintenance() {
 		const result = runMaintenance(this.db, this.config, { budget: 0 });
-		this.evictVectors([...result.archived_ids, ...result.purged_ids]);
+		evictVectors(this.vstore, [...result.archived_ids, ...result.purged_ids]);
 		this.retireConflicts([...result.archived_ids, ...result.purged_ids]);
 		this.vstore.compact?.();
 		this.db.pragma("optimize");
@@ -11279,25 +12200,19 @@ var MemoryStore = class {
 	* loop until `deferred === 0` — `budget` bounds MEMORY as well as mission, since the pass reads
 	* every selected row's `content` before rebuilding the first one.
 	*
-	* The in-flight guard is here rather than at the callers because the callers CAN overlap: the
-	* plugin's heartbeat and `maintenance` are both periodic, and `staleEntityRows` is ORDERED, so
-	* two concurrent passes would select the same rows and re-tag them twice. Overlap is not
-	* corruption (each fact is stamped in its own transaction) — it is duplicated mission in a
-	* single-threaded process. A pass that finds one running reports `skipped` and does nothing.
-	*
-	* `budget` is clamped at 0: SQLite reads a negative LIMIT as "no limit" (`LIMIT -1`), so a
-	* caller asking for "-1 rows" would silently get the whole corpus — the opposite of bounded.
+	* The loop, the budget clamp, the in-flight guard and the `{rebuilt, deferred, skipped}` report all
+	* live in `store/entity_sweep.ts` now — this method is memory's adapter for it, so knowledge's
+	* entity leg and this one cannot drift apart again. What stays HERE is the domain half: the stale
+	* selection (`facts.staleEntityRows`, ACTIVE facts only) and the per-fact write below.
 	*/
 	async reindexEntities(budget = ENTITY_SWEEP_BATCH) {
-		if (this.entitySweepInFlight) return {
-			rebuilt: 0,
-			deferred: this.facts.countStaleEntities(1),
-			skipped: true
-		};
-		this.entitySweepInFlight = true;
-		try {
-			const rows = this.facts.staleEntityRows(1, Math.max(0, Math.floor(budget)));
-			for (const row of rows) {
+		return await sweepVersionedEntities({
+			staleEntityBatch: (limit) => ({
+				total: this.facts.countStaleEntities(1),
+				rows: this.facts.staleEntityRows(1, limit)
+			}),
+			staleEntityCount: () => this.facts.countStaleEntities(1),
+			extractAndWriteEntities: async (row) => {
 				const tokens = await tagText(row.content);
 				const entityWrites = normalizeEntityWrites(entitiesFromTokens(tokens, row.content));
 				const entities = entityWrites.map((e) => e.name);
@@ -11312,15 +12227,11 @@ var MemoryStore = class {
 					this.facts.setEntitiesVersion([row.fact_id], 1);
 					this.facts.requeueConflictCheck([row.fact_id]);
 				})();
+			},
+			onRowError: (row, error) => {
+				retrievalLogger().warn(`memory entity sweep: fact ${String(row.fact_id)} could not be rebuilt (${error instanceof Error ? error.message : String(error)}) — it keeps its old stamp; the next pass retries it`);
 			}
-			return {
-				rebuilt: rows.length,
-				deferred: this.facts.countStaleEntities(1),
-				skipped: false
-			};
-		} finally {
-			this.entitySweepInFlight = false;
-		}
+		}, this.entitySweepGuard, { budget });
 	}
 	/**
 	* A fact left the ACTIVE corpus: retire the open conflicts that name it, so
@@ -11331,10 +12242,6 @@ var MemoryStore = class {
 	retireConflicts(factIds) {
 		this.contradictions.resolveForFacts(factIds);
 	}
-	/** Drop vectors of archived/purged facts from the live index (batched). */
-	evictVectors(factIds) {
-		evictVectors(this.vstore, factIds);
-	}
 	/**
 	* Entities that co-occur with `entity` across ACTIVE facts, ranked by occurrence
 	* count. Archived (incl. superseded) facts are excluded — their entities are not
@@ -11382,17 +12289,7 @@ var MemoryStore = class {
 	}
 	/** Hybrid search over the memory corpus (semantic + FTS + entity Jaccard [+ HRR probe] via fusion). */
 	async search(input) {
-		const result = await hybridSearch(this.hybridDeps(input), {
-			query: input.query,
-			limit: input.limit,
-			maxTokens: input.maxTokens,
-			queryVector: input.queryVector,
-			recordStats: input.recordStats,
-			floors: input.floors,
-			...input.includeScores === void 0 ? {} : { includeScores: input.includeScores },
-			...input.relaxLegs === void 0 ? {} : { relaxLegs: input.relaxLegs },
-			...input.rewriteQuery === void 0 ? {} : { rewriteQuery: input.rewriteQuery }
-		});
+		const result = await runHybridSearch(this.hybridDeps(input), input.query, input);
 		return {
 			hits: result.hits,
 			degraded: result.degraded,
@@ -11407,10 +12304,7 @@ var MemoryStore = class {
 	* fact→hit mapping, and what to do with the hits the caller actually receives.
 	*/
 	hybridDeps(input) {
-		return {
-			kind: "memory",
-			config: this.config,
-			semantic: this.semantic,
+		return makeHybridDeps("memory", this.config, this.semantic, {
 			legs: (ctx) => this.searchLegs(input, ctx),
 			texts: (ids) => this.loadTexts(ids),
 			hits: (ranked, texts) => {
@@ -11420,7 +12314,7 @@ var MemoryStore = class {
 			onReturn: (kept) => {
 				if (input.track !== false) this.reinforce(kept.map((h) => h.ref_id));
 			}
-		};
+		});
 	}
 	/**
 	* The memory legs: semantic, FTS, entity Jaccard, and — for `recall.probe` — the HRR probe.
@@ -11442,49 +12336,18 @@ var MemoryStore = class {
 		const qEntities = Array.from(new Set((await extractEntities(ctx.query)).map((e) => e.name)));
 		const anchors = qEntities.length > 0 ? selectAnchors(qEntities, this.entities.activeDocFrequency(qEntities), this.facts.countActive()) : [];
 		const candidates = anchors.length > 0 ? this.entities.candidateFactsForAnyEntity(anchors, input.category, ctx.legCap, qEntities.length, 3, input.source) : [];
-		/**
-		* Wrap one leg's raw scores. `capped` must be measured on the RAW set (before the relevance
-		* floor): the floor removes the tail anyway, and deriving the flag from the floored size would
-		* erase the "this leg was cut at legCap" signal exactly when it bound.
-		*/
-		const leg = (scores, weight, raw) => ({
-			weight,
-			scores,
-			capped: (raw ?? scores).size === ctx.legCap
-		});
+		const runner = makeLegRunner(ctx);
 		const ftsRaw = this.ftsPath(ctx.query, input.category, ctx.legCap, input.source);
-		const ftsFloored = applyTermFloor(ftsRaw, this.loadTexts([...ftsRaw.keys()]), ctx.query, ctx.floors.fts);
+		const ftsLeg = runner.term("fts", ftsRaw, this.loadTexts([...ftsRaw.keys()]), ctx.query, ctx.weights.fts, ctx.floors.fts);
 		const jaccardRaw = this.jaccardPath(anchors, qEntities.length, candidates);
-		const jaccardFloored = applyScoreFloor(jaccardRaw, ctx.floors.jaccard);
-		const jaccardLeg = {
-			...leg(jaccardFloored.scores, ctx.weights.jaccard, jaccardRaw),
-			leg: "jaccard",
-			droppedByFloor: jaccardFloored.dropped
-		};
+		const jaccardLeg = runner.scored("jaccard", jaccardRaw, ctx.weights.jaccard, ctx.floors.jaccard);
 		const legs = [
-			ctx.semAvail ? this.semanticPath(ctx.query, input.category, ctx.overFetch, ctx.queryVector, ctx.onQueryVector, input.source).then((raw) => {
-				const floored = applyScoreFloor(raw, ctx.floors.semantic);
-				return {
-					weight: ctx.weights.semantic,
-					scores: floored.scores,
-					leg: "semantic",
-					droppedByFloor: floored.dropped
-				};
-			}) : {
-				weight: ctx.weights.semantic,
-				scores: /* @__PURE__ */ new Map(),
-				leg: "semantic",
-				droppedByFloor: 0
-			},
+			ctx.semAvail ? this.semanticPath(ctx.query, input.category, ctx.overFetch, ctx.queryVector, ctx.onQueryVector, input.source).then((raw) => runner.semantic(raw, ctx.weights.semantic, ctx.floors.semantic)) : runner.semanticOff(ctx.weights.semantic),
 			Promise.resolve(jaccardLeg),
-			{
-				...leg(ftsFloored.scores, ctx.weights.fts, ftsRaw),
-				leg: "fts",
-				droppedByFloor: ftsFloored.dropped
-			}
+			ftsLeg
 		];
-		if (input.includeHrr) legs.push(Promise.resolve(leg(this.hrrPath(ctx.query, qEntities, [...jaccardFloored.scores.keys()], input.category, ctx.legCap, candidates.length === 0, input.source), ctx.weights.jaccard)));
-		if (this.config.retriever.time_window) legs.push(Promise.resolve(leg(this.timeWindowPath(ctx.query, input.category, ctx.legCap, input.source), ctx.weights.jaccard)));
+		if (input.includeHrr) legs.push(Promise.resolve(runner.plain(this.hrrPath(ctx.query, qEntities, [...jaccardLeg.scores.keys()], input.category, ctx.legCap, candidates.length === 0, input.source), ctx.weights.jaccard)));
+		if (this.config.retriever.time_window) legs.push(Promise.resolve(runner.plain(this.timeWindowPath(ctx.query, input.category, ctx.legCap, input.source), ctx.weights.jaccard)));
 		return legs;
 	}
 	/**
@@ -11609,18 +12472,22 @@ var MemoryStore = class {
 	* Semantic leg. `queryVector` short-circuits the encode when the caller already
 	* encoded this exact query (the cross-store router does, for both stores at once);
 	* `onVector` publishes the vector this leg actually used, so the relaxed retry pass can reuse it
-	* instead of re-encoding (performance review §7.7 / P8).
+	* instead of re-encoding (performance review §7.7 / P8). The flow is shared
+	* (`store/legs.ts#semanticLeg`); the only memory-specific piece is the filter — the vstore has no
+	* notion of status/category/source, so candidates go through the DB and archived/purged facts,
+	* other categories and other sources never leak into the leg.
 	*/
 	async semanticPath(query, category, k, queryVector, onVector, source) {
-		const vec = queryVector ?? await this.semantic.encode(query);
-		if (vec.length !== this.vstore.dim) throw new RetrievalInputError(`queryVector 维度不符：${vec.length} != ${this.vstore.dim}`);
-		onVector?.(vec);
-		const topk = this.vstore.topk(vec, Math.max(50, k));
-		if (!topk.length) return /* @__PURE__ */ new Map();
-		const allowed = new Set(this.facts.activeIdsIn(topk.map((t) => t.id), category, source));
-		const out = /* @__PURE__ */ new Map();
-		for (const t of topk) if (allowed.has(t.id)) out.set(t.id, t.score);
-		return out;
+		return semanticLeg({
+			query,
+			k,
+			queryVector,
+			onVector,
+			encode: (q) => this.semantic.encode(q),
+			dim: this.vstore.dim,
+			topk: (vec, n) => this.vstore.topk(vec, n),
+			filterTopk: (ids) => new Set(this.facts.activeIdsIn(ids, category, source))
+		});
 	}
 	/**
 	* HRR entity-probe path: phase similarity between the query's entity bundle and
@@ -11689,21 +12556,20 @@ var MemoryStore = class {
 	* semantic, why it must be synchronous, and how the bar itself was measured.
 	*/
 	lexicalProbe(text, stopAt = Number.POSITIVE_INFINITY) {
-		return probeTerms(text, (term) => {
-			const fts = buildFtsQuery(term, this.ftsTokenizer);
-			return fts !== null && this.facts.ftsSearch(fts, void 0, 1).length > 0;
-		}, stopAt);
+		return probeStoreTerms(text, this.ftsTokenizer, (fts) => this.facts.ftsSearch(fts, void 0, 1).length > 0, stopAt);
 	}
 	ftsPath(query, category, cap, source) {
-		const ftsQuery = buildFtsQuery(query, this.ftsTokenizer);
-		if (ftsQuery) {
-			const rows = this.facts.ftsSearch(ftsQuery, category, cap, source);
-			return new Map(rows.map((r) => [r.id, -r.rank]));
-		}
-		const terms = substringTerms(query);
-		if (terms.length === 0) return /* @__PURE__ */ new Map();
-		const rows = this.facts.ftsSubstringSearch(terms, category, cap, source);
-		return new Map(rows.map((r) => [r.id, r.rank]));
+		return ftsLeg({
+			query,
+			cap,
+			scope: {
+				category,
+				source
+			},
+			tokenizer: this.ftsTokenizer,
+			search: (ftsQuery, scope, limit) => this.facts.ftsSearch(ftsQuery, scope.category, limit, scope.source),
+			substringSearch: (terms, scope, limit) => this.facts.ftsSubstringSearch(terms, scope.category, limit, scope.source)
+		});
 	}
 	/**
 	* Entity leg over the precomputed candidate set (see `searchLegs`): the candidates are the facts
@@ -11810,7 +12676,7 @@ var MemoryStore = class {
 				supersededId
 			};
 		})();
-		if (supersededId !== null) this.evictVectors([supersededId]);
+		if (supersededId !== null) evictVectors(this.vstore, [supersededId]);
 		return result;
 	}
 	/**
@@ -12179,10 +13045,7 @@ var ChunksDao = class {
 	}
 	/** Record which extraction rules produced a chunk's entity rows (see `ENTITY_EXTRACTOR_VERSION`). */
 	setEntitiesVersion(ids, version) {
-		for (const batch of batches(ids)) {
-			const { placeholders, values } = inList(batch);
-			this.db.prepare(`UPDATE doc_chunks SET entities_version = ? WHERE chunk_id IN (${placeholders})`).run(version, ...values);
-		}
+		setEntitiesVersionBatch(this.db, "doc_chunks", "chunk_id", ids, version);
 	}
 	/** Every persisted chunk vector, for rebuilding the in-memory index at open. */
 	/**
@@ -12195,14 +13058,68 @@ var ChunksDao = class {
 	vectorRows() {
 		return this.db.prepare("SELECT chunk_id AS id, semantic_vector AS vec, embedding_model AS embedding_model FROM doc_chunks WHERE semantic_vector IS NOT NULL").all();
 	}
+	/**
+	* Vector-space health of the WHOLE chunk corpus, by kind, WITHOUT decoding a single blob.
+	*
+	* The same two counts the open-time warning reports (`stale` = wrong width, `space_stale` = same
+	* width but another recorded space — `embedding_model IS NOT` is null-safe, so a row with no
+	* recorded space counts as foreign exactly like the JS comparison in `reloadIndex`) plus `missing`
+	* (no vector at all), which is the third reason the semantic leg cannot use a chunk.
+	*
+	* This is what lets the shared repair flow read "what is stale" cheaply per slice instead of
+	* re-scanning and hashing the corpus (`corpusState` reads every text; a batched migration must
+	* not).
+	*/
+	vectorSpaceCounts(space, expectedBytes) {
+		const row = this.db.prepare(`SELECT
+           COALESCE(SUM(CASE WHEN semantic_vector IS NULL THEN 1 ELSE 0 END), 0) AS missing,
+           COALESCE(SUM(CASE WHEN semantic_vector IS NOT NULL AND length(semantic_vector) != :bytes THEN 1 ELSE 0 END), 0) AS stale,
+           COALESCE(SUM(CASE WHEN semantic_vector IS NOT NULL AND length(semantic_vector) = :bytes AND embedding_model IS NOT :space THEN 1 ELSE 0 END), 0) AS space_stale
+         FROM doc_chunks`).get({
+			bytes: expectedBytes,
+			space
+		});
+		return {
+			stale: Number(row?.stale ?? 0),
+			space_stale: Number(row?.space_stale ?? 0),
+			missing: Number(row?.missing ?? 0)
+		};
+	}
+	/** Chunks with no persisted vector — the repair flow's `missing` term in `remaining`. */
+	countMissingVectors() {
+		return Number(this.db.prepare("SELECT COUNT(*) AS n FROM doc_chunks WHERE semantic_vector IS NULL").get()?.n ?? 0);
+	}
+	/**
+	* Chunks the semantic leg cannot use (no vector / wrong width / another space), bounded and
+	* ordered by id — the repair flow's encode source.
+	*
+	* The content-hash check `vectorReusable` adds is deliberately NOT here: a chunk whose vector is
+	* in the current space is usable even if its text was edited behind the store's back, and that
+	* (rarer) case belongs to `kb_reindex`, which re-derives every leg. Repairing the SPACE must not
+	* pay a jieba/hash pass over the corpus to find rows the space change did not touch.
+	*/
+	staleVectorRows(space, expectedBytes, limit) {
+		const bound = Number.isFinite(limit) ? Math.max(0, Math.floor(limit)) : -1;
+		return this.db.prepare(`SELECT chunk_id AS chunk_id, text AS text FROM doc_chunks
+          WHERE semantic_vector IS NULL OR length(semantic_vector) != :bytes OR embedding_model IS NOT :space
+          ORDER BY chunk_id ASC LIMIT :limit`).all({
+			bytes: expectedBytes,
+			space,
+			limit: bound
+		});
+	}
 	count() {
 		return this.db.prepare("SELECT COUNT(*) AS n FROM doc_chunks").get().n;
 	}
 	/**
-	* Replace the entity rows of the given chunks in one transaction (`replace` clears the
-	* old rows first — used by reindex, where the extractor may have changed).
+	* Replace the entity rows of the given chunks in one transaction.
+	*
+	* `replace` is REQUIRED, not defaulted: `true` clears the old rows first (the entity sweep, where
+	* the extractor may have changed), `false` is the ingest path, where the chunk ids are freshly
+	* inserted and an absent old row set. A default would let one caller silently inherit the other's
+	* semantics — an extra `DELETE` per chunk on ingest, or an append-on-top-of-stale sweep.
 	*/
-	replaceEntities(rows, replace = false) {
+	replaceEntities(rows, replace) {
 		const del = this.db.prepare("DELETE FROM chunk_entities WHERE chunk_id = ?");
 		const ins = this.db.prepare("INSERT OR IGNORE INTO chunk_entities (chunk_id, name) VALUES (?, ?)");
 		this.db.transaction(() => {
@@ -12214,17 +13131,12 @@ var ChunksDao = class {
 	}
 	/** Batched entity bags: `Map<chunkId, names>` (ids with none are absent). */
 	entityBags(ids) {
-		const out = /* @__PURE__ */ new Map();
-		for (const batch of batches(ids)) {
-			const { placeholders, values } = inList(batch);
-			const rows = this.db.prepare(`SELECT chunk_id, name FROM chunk_entities WHERE chunk_id IN (${placeholders})`).all(...values);
-			for (const r of rows) {
-				const list = out.get(r.chunk_id);
-				if (list) list.push(r.name);
-				else out.set(r.chunk_id, [r.name]);
-			}
-		}
-		return out;
+		return entityBags(this.db, ids, {
+			table: "chunk_entities",
+			keyColumn: "chunk_id",
+			nameColumn: "name",
+			seedEmpty: false
+		});
 	}
 	/** Chunk body + owning-document identity for the fused candidate ids. */
 	hits(ids) {
@@ -12264,13 +13176,48 @@ var ChunksDao = class {
          JOIN documents d ON d.doc_id = dc.doc_id
          WHERE (? IS NULL OR d.domain = ?)`).all(domain ?? null, domain ?? null);
 	}
+	/**
+	* Chunk rows whose `chunk_entities` were produced by OLDER extraction rules — the entity sweep's
+	* selection, bounded and ordered by id.
+	*
+	* `COALESCE(entities_version, 0) < :version`, not `entities_version != :version`: the column is
+	* NULLABLE on purpose (a row written before the derived-state columns existed must look stale
+	* exactly once and be adopted by the first rebuild — see `ChunkStateRow`), and a bare `<` would
+	* evaluate to NULL for those rows and let them hide from the sweep forever.
+	*
+	* The predicate is index-served in id order (`doc_chunks` is keyed by `chunk_id`), so the LIMIT
+	* bounds what is READ, not only what is rebuilt — the same property `FactsDao.staleEntityRows`
+	* documents for the memory side.
+	*/
+	chunkEntityRows(version, limit, domain) {
+		return this.db.prepare(`SELECT dc.chunk_id AS chunk_id, dc.text AS text
+           FROM doc_chunks dc
+           JOIN documents d ON d.doc_id = dc.doc_id
+          WHERE COALESCE(dc.entities_version, 0) < :version AND (:domain IS NULL OR d.domain = :domain)
+          ORDER BY dc.chunk_id ASC LIMIT :limit`).all({
+			version,
+			limit,
+			domain: domain ?? null
+		});
+	}
+	/** How many chunks still carry entity rows from older rules — the sweep's `deferred` source. */
+	countStaleEntityChunks(version, domain) {
+		return Number(this.db.prepare(`SELECT COUNT(*) AS n
+             FROM doc_chunks dc
+             JOIN documents d ON d.doc_id = dc.doc_id
+            WHERE COALESCE(dc.entities_version, 0) < :version AND (:domain IS NULL OR d.domain = :domain)`).get({
+			version,
+			domain: domain ?? null
+		})?.n ?? 0);
+	}
 	/** Rebuild the FTS index from the content table (write-path maintenance). */
 	rebuildFts() {
 		this.db.exec("INSERT INTO doc_chunks_fts(doc_chunks_fts) VALUES('rebuild')");
 	}
 	/** Active chunks sharing at least one entity name with the query (jaccard candidate set). */
 	/**
-	* Entity-overlap candidates, most-shared first and CAPPED (see the memory store's sibling).
+	* Entity-overlap candidates, highest-score first and CAPPED (see the memory store's sibling;
+	* the score/order tail itself lives in `./shared.js#entityCandidateTail`).
 	*
 	* `limit` is applied per name-batch and the batches are unioned, so the result is bounded by
 	* `limit x ceil(names/batch)` — corpus-independent, which is what this query can promise. The
@@ -12280,11 +13227,19 @@ var ChunksDao = class {
 	* of the truth. (The memory store's sibling does not batch, so its single `LIMIT` is already exact.)
 	*/
 	candidatesByEntityNames(names, domain, source, limit, queryWidth, widthCap) {
-		if (limit <= 0) return [];
-		const out = /* @__PURE__ */ new Set();
-		for (const batch of batches(names)) {
-			const { placeholders, values } = inList(batch);
-			const rows = this.db.prepare(`SELECT ce.chunk_id AS chunk_id, COUNT(*) AS shared,
+		return entityCandidates(this.db, {
+			names,
+			filterParams: [
+				domain ?? null,
+				domain ?? null,
+				source ?? null,
+				source ?? null
+			],
+			limit,
+			queryWidth,
+			widthCap,
+			batchNames: true,
+			sql: (placeholders) => `SELECT ce.chunk_id AS id, COUNT(*) AS shared,
                   (SELECT COUNT(*) FROM chunk_entities x WHERE x.chunk_id = ce.chunk_id) AS total
              FROM chunk_entities ce
              JOIN doc_chunks dc ON dc.chunk_id = ce.chunk_id
@@ -12295,12 +13250,8 @@ var ChunksDao = class {
             -- removed document's chunks out of a result is the JOIN itself.
             WHERE ce.name IN (${placeholders})
               AND (? IS NULL OR d.domain = ?) AND (? IS NULL OR d.source = ?)
-            GROUP BY ce.chunk_id
-            ORDER BY (CAST(shared AS REAL) / (? + MIN(total - shared, ?))) DESC, total ASC, ce.chunk_id ASC
-            LIMIT ?`).all(...values, domain ?? null, domain ?? null, source ?? null, source ?? null, queryWidth, widthCap, limit);
-			for (const r of rows) out.add(r.chunk_id);
-		}
-		return [...out];
+            ${entityCandidateTail("ce.chunk_id")}`
+		});
 	}
 	/**
 	* How many chunks carry each name — the knowledge side of the entity leg's document frequency.
@@ -12310,12 +13261,10 @@ var ChunksDao = class {
 	* all chunks, which is the population the leg ranks.
 	*/
 	docFrequency(names) {
-		const out = /* @__PURE__ */ new Map();
-		if (!names.length) return out;
-		const { placeholders, values } = inList(names);
-		const rows = this.db.prepare(`SELECT name, COUNT(*) AS df FROM chunk_entities WHERE name IN (${placeholders}) GROUP BY name`).all(...values);
-		for (const row of rows) out.set(row.name, Number(row.df));
-		return out;
+		return queryDocFrequency(this.db, names, {
+			from: " FROM chunk_entities",
+			nameExpr: "name"
+		});
 	}
 	/** FTS leg (`bm25` rank; negated by the caller so higher = better). */
 	ftsSearch(ftsQuery, domain, source, limit) {
@@ -12335,14 +13284,17 @@ var ChunksDao = class {
 	* the domain/source filter lives.
 	*/
 	ftsSubstringSearch(terms, domain, source, limit) {
-		const { any, count, params } = likeSubstring("dc.text", terms);
-		if (params.length === 0) return [];
-		return this.db.prepare(`SELECT dc.chunk_id AS id, ${count} AS rank
+		return likeSubstringLeg(this.db, "dc.text", terms, ({ any, count }) => `SELECT dc.chunk_id AS id, ${count} AS rank
            FROM doc_chunks dc
            JOIN documents d ON d.doc_id = dc.doc_id
           WHERE (? IS NULL OR d.domain = ?) AND (? IS NULL OR d.source = ?) AND (${any})
           ORDER BY rank DESC, dc.chunk_id ASC
-          LIMIT ?`).all(...params, domain ?? null, domain ?? null, source ?? null, source ?? null, ...params, limit ?? -1);
+          LIMIT ?`, [
+			domain ?? null,
+			domain ?? null,
+			source ?? null,
+			source ?? null
+		], limit);
 	}
 };
 //#endregion
@@ -13649,6 +14601,15 @@ var KnowledgeStore = class {
 	/** > 0 while a batch (directory import) is writing: commits and baseline refreshes wait. */
 	deferCorpusWrites = 0;
 	/**
+	* Identity object for the shared entity sweep's in-flight guard (`store/entity_sweep.ts`).
+	*
+	* The guard itself lives in that module; this is only the per-store identity it keys on. It exists
+	* as a field — rather than the adapter object, which is built per call — because the guard must
+	* survive between two overlapping calls: `reindex` can be reached from a tool call and the
+	* settings-page button at once, and both would select the same stale chunks.
+	*/
+	entitySweepGuard = {};
+	/**
 	* Per-file stamps (`path → mtimeMs:size`) and the file-set they were taken from, so a reconcile
 	* can ask "what changed?" for the price of one `stat` per document instead of reading and
 	* hashing the whole corpus. `null` = no baseline yet.
@@ -13696,37 +14657,27 @@ var KnowledgeStore = class {
 		this.reloadIndex();
 	}
 	/**
-	* Rebuild the in-memory vstore from persisted chunk vectors.
+	* Rebuild the in-memory vstore from persisted chunk vectors, and say loudly what belongs to
+	* another vector space.
 	*
-	* Also detects a VECTOR-SPACE change, which the reload itself cannot see: `reloadVectorIndex`
-	* checks the width, and a different model at the same width produces dim-valid vectors that are
-	* then ranked against the current query's — two spaces mixed in one index, with no error anywhere.
-	* The memory store always said something about this; the knowledge store did not, so a model swap
-	* degraded every semantic query here until someone happened to run `kb_reindex`.
+	* Also detects a VECTOR-SPACE change, which the reload itself cannot see: the reload checks the
+	* width, and a different model at the same width produces dim-valid vectors that are then ranked
+	* against the current query's — two spaces mixed in one index, with no error anywhere.
+	*
+	* The reload, the count and the warning are the SHARED open-time step (`store/vector_repair.ts`),
+	* which is what turned the knowledge store from "warns about a swapped model but never repairs it"
+	* into the same automatic path memory has always had; this store's half is the row read. The
+	* manual entry stays `vectors --fix` (the vector-only repair); `kb_reindex` remains the full
+	* FTS + entities + vectors re-entry.
 	*/
 	reloadIndex() {
-		const space = this.vectorSpace();
-		const persisted = this.chunks.vectorRows();
-		reloadVectorIndex(this.vstore, persisted, "knowledge");
-		let stale = 0;
-		let spaceStale = 0;
-		let legacy = 0;
-		const expectedBytes = this.vstore.dim * 4;
-		for (const row of persisted) {
-			if (!row.vec || row.vec.byteLength !== expectedBytes) {
-				stale++;
-				continue;
-			}
-			if (row.embedding_model !== space) {
-				spaceStale++;
-				if (isPreFingerprintSpace(row.embedding_model)) legacy++;
-			}
-		}
-		reportStaleVectors("knowledge", space, {
-			stale,
-			space_stale: spaceStale,
-			legacy
-		}, "`avantf-mem kb reindex` (MCP/plugin: `kb_reindex`)");
+		loadVectorIndex({
+			store: "knowledge",
+			vstore: this.vstore,
+			rows: this.chunks.vectorRows(),
+			space: this.vectorSpace(),
+			manualEntry: "`avantf-mem vectors --fix` (MCP/plugin: `mem_admin vectors_fix`; `kb_reindex` re-runs FTS/entities too)"
+		});
 	}
 	/**
 	* The write-side domain allowlist AND the 知识页 picker's data, in one place: the configured
@@ -14005,7 +14956,7 @@ var KnowledgeStore = class {
 				reusable
 			};
 		}).immediate();
-		this.evictVectors(result.oldChunkIds);
+		evictVectors(this.vstore, result.oldChunkIds);
 		const indexed = await this.indexChunks(result.newChunkIds, result.reusable);
 		return {
 			doc_id: result.doc_id,
@@ -14042,10 +14993,6 @@ var KnowledgeStore = class {
 			return { file_error: error instanceof Error ? error.message : String(error) };
 		}
 	}
-	/** Batched eviction from the live vector index (removeMany when the backend supports it). */
-	evictVectors(ids) {
-		evictVectors(this.vstore, ids);
-	}
 	/** The resolved ingestion boundary (see `ingest_guard.ts`). */
 	get ingestLimits() {
 		return this.kbConfig.ingest;
@@ -14168,7 +15115,8 @@ var KnowledgeStore = class {
 		};
 	}
 	/**
-	* Encode texts ONE AT A TIME, writing every `WRITE_BATCH` vectors in one transaction.
+	* This store's half of the shared encode-and-persist flow (`store/vector_repair.ts`): the backend
+	* call, the live index and the `WRITE_BATCH` transaction this store measured its way into.
 	*
 	* The model call is deliberately NOT batched, and that is a MEASURED decision, not an omission:
 	* a batched forward pass pads each item to the longest in its group, and real chunks span 53–550
@@ -14179,34 +15127,43 @@ var KnowledgeStore = class {
 	* length-sorted) for callers whose texts suit it.
 	*
 	* What DID pay off is the write side: one commit per `WRITE_BATCH` chunks instead of one per
-	* chunk (measured 14.2 µs/row vs 2.2 µs/row), and the transaction never spans an `await`.
+	* chunk (measured 14.2 µs/row vs 2.2 µs/row), and the transaction never spans an `await` — that
+	* is the `writeBatch` below.
 	*/
-	async encodeAndStore(rows, space) {
-		let encoded = 0;
-		let failed = 0;
-		for (let i = 0; i < rows.length; i += WRITE_BATCH) {
-			const group = rows.slice(i, i + WRITE_BATCH);
-			const writes = [];
-			for (const r of group) try {
-				const vec = await this.semantic.encode(r.text);
-				this.vstore.add(r.chunk_id, vec);
-				writes.push({
-					chunk_id: r.chunk_id,
-					bytes: float32ToBytes(vec),
+	encodeWriteTarget(space) {
+		return {
+			store: "knowledge",
+			space,
+			encode: (text) => this.semantic.encode(text),
+			add: (id, vec) => {
+				this.vstore.add(id, vec);
+			},
+			write: (writes) => {
+				this.chunks.setVectors(writes.map((w) => ({
+					chunk_id: w.id,
+					bytes: w.bytes,
 					embeddingModel: space
-				});
-			} catch {
-				failed += 1;
-			}
-			if (!writes.length) continue;
-			try {
-				this.chunks.setVectors(writes);
-				encoded += writes.length;
-			} catch {
-				failed += writes.length;
-				this.evictVectors(writes.map((w) => w.chunk_id));
+				})));
+			},
+			writeBatch: WRITE_BATCH,
+			onWriteError: (writes) => {
+				evictVectors(this.vstore, writes.map((w) => w.id));
 			}
-		}
+		};
+	}
+	/**
+	* Encode texts one at a time and persist them in `WRITE_BATCH` transactions.
+	*
+	* A failed chunk is skipped, not thrown: the rows are already committed and their old vectors
+	* evicted by the ingest path, so a throw here would leave the caller with a failed ingest and NO
+	* COUNT of what was skipped. The shortfall travels back to the tool result
+	* (`IngestResult.vectors_failed`) instead of living only in a log line.
+	*/
+	async encodeAndStore(rows, space) {
+		const { encoded, failed } = await encodeAndPersist(rows.map((r) => ({
+			id: r.chunk_id,
+			text: r.text
+		})), this.encodeWriteTarget(space));
 		if (failed > 0) retrievalLogger().warn(`kb index: ${String(failed)} of ${String(rows.length)} chunk vector(s) were not written — run kb_reindex to retry (the text/entity/FTS indexes are complete; only the semantic vectors are affected)`);
 		return {
 			encoded,
@@ -14223,6 +15180,102 @@ var KnowledgeStore = class {
 		return vectorSpaceOf(this.semantic, this.config.semantic.local_model);
 	}
 	/**
+	* Cheapest possible DETECTION of "the embedding space changed under this store": counts of
+	* persisted chunk vectors whose width or recorded space id no longer matches the one this store
+	* writes into. Reads blob LENGTHS only — never decodes — so the startup warning and the background
+	* drive can afford it at any corpus size.
+	*/
+	vectorSpaceHealth() {
+		const c = this.vectorSpaceCounts();
+		return {
+			stale: c.stale,
+			space_stale: c.space_stale
+		};
+	}
+	/** {@link vectorSpaceHealth} plus `missing`, the third term of the repair flow's `remaining`. */
+	vectorSpaceCounts() {
+		return this.chunks.vectorSpaceCounts(this.vectorSpace(), this.vstore.dim * 4);
+	}
+	/** Async bootstrap the semantic backend (the shared flow's explicit-fix warmup). */
+	async warmupSemantic() {
+		await (this.semantic.warmUp?.() ?? Promise.resolve());
+		return this.semantic.isAvailable();
+	}
+	/**
+	* This store's half of the shared repair flow (`store/vector_repair.ts`): the primitives the flow
+	* steps. The flow itself — batch size, event-loop yield, stop / resume / no-progress rules,
+	* `semantic.auto_migrate`, the dry-run split — lives there once, for both stores.
+	*/
+	vectorRepairTarget() {
+		return {
+			store: "knowledge",
+			manualEntry: "`avantf-mem vectors --fix` (MCP/plugin: `mem_admin vectors_fix`; `kb_reindex` re-runs FTS/entities too)",
+			vectorSpace: () => this.vectorSpace(),
+			semanticAvailable: () => this.semantic.isAvailable(),
+			autoMigrate: () => this.config.semantic.auto_migrate,
+			vectorSpaceHealth: () => this.vectorSpaceHealth(),
+			missingVectorCount: () => this.chunks.countMissingVectors(),
+			classifyVectors: () => this.classifyRepairVectors(),
+			dropVectors: () => 0,
+			reencodeVectors: (limit) => this.reencodeStaleChunks(limit),
+			warmup: () => this.warmupSemantic()
+		};
+	}
+	/**
+	* The chunks the semantic leg cannot use (no vector / wrong width / another space). One SQL
+	* aggregate over blob lengths; `dropIds` is empty because knowledge overwrites in place.
+	*/
+	classifyRepairVectors() {
+		const c = this.vectorSpaceCounts();
+		return {
+			stale: c.stale,
+			space_stale: c.space_stale,
+			missing: c.missing,
+			dropIds: []
+		};
+	}
+	/**
+	* Encode + persist up to `limit` chunks the semantic leg cannot use, bounded and ordered by id.
+	*
+	* It does NOT re-extract entities or rebuild FTS: that is `kb_reindex`'s job, and the whole point
+	* of the automatic repair is that the vector half can run on its own — which is exactly the
+	* objection the "known boundary" in DESIGN §20 used to raise against a background run.
+	*/
+	async reencodeStaleChunks(limit) {
+		const space = this.vectorSpace();
+		const rows = this.chunks.staleVectorRows(space, this.vstore.dim * 4, limit);
+		if (!rows.length) return {
+			encoded: 0,
+			failed: 0
+		};
+		return await this.encodeAndStore(rows, space);
+	}
+	/**
+	* The explicit, unbounded repair behind `mem_admin vectors_fix` / `avantf-mem vectors --fix`.
+	* `dry_run` previews every count without writing — and without loading the model, which is why
+	* the preview also reports `would_warm` (see the contract's `VectorsFixStoreReport`).
+	*/
+	async vectorsFix(dryRun = false) {
+		return (await repairVectorSlice(this.vectorRepairTarget(), { dryRun })).report;
+	}
+	/**
+	* ONE bounded slice of the vector-space migration: at most `batchSize` chunks are re-encoded, so
+	* the caller keeps control of the event loop between slices. This is the unit the background
+	* migration ({@link migrateVectors}) and its tests drive.
+	*/
+	async migrateVectorsBatch(batchSize = 16) {
+		return await migrateVectorSlice(this.vectorRepairTarget(), batchSize);
+	}
+	/**
+	* Drive the bounded background migration for this store until it is current, the model is
+	* unavailable, or `shouldStop()` turns true (plugin unmount / process shutdown). The loop, the
+	* `semantic.auto_migrate` switch, the no-progress rule and the store-named logging all live in the
+	* shared flow (`store/vector_repair.ts`); this is the one-store entry.
+	*/
+	async migrateVectors(opts = {}) {
+		return await driveVectorRepair(this.vectorRepairTarget(), opts);
+	}
+	/**
 	* A stored vector is reusable when it exists, matches the space, and its text is unchanged.
 	*
 	* The three checks answer different questions, and the hash is deliberately the RAREST of them
@@ -14236,17 +15289,43 @@ var KnowledgeStore = class {
 		if (row.embedding_model !== space) return false;
 		return row.content_hash === contentHash(row.text);
 	}
-	/** One transaction replacing the entity rows of the given chunks (shared by ingest + reindex). */
-	async replaceChunkEntities(rows, replace = false) {
+	/**
+	* Extract one chunk's entity names, bounded by `MAX_ENTITIES_PER_CHUNK`.
+	*
+	* The bound is here, not in either caller: it is a property of what `chunk_entities` may hold for
+	* one chunk, and the ingest path and the sweep must not disagree about it.
+	*/
+	async extractRowEntities(text) {
+		return (await extractEntities(text)).map((e) => e.name).slice(0, MAX_ENTITIES_PER_CHUNK);
+	}
+	/** One transaction replacing the entity rows of the given chunks (the ingest path). */
+	async replaceChunkEntities(rows) {
 		const extracted = [];
-		for (const r of rows) {
-			const names = (await extractEntities(r.text)).map((e) => e.name).slice(0, MAX_ENTITIES_PER_CHUNK);
-			extracted.push({
-				chunk_id: r.chunk_id,
-				names
-			});
-		}
-		this.chunks.replaceEntities(extracted, replace);
+		for (const r of rows) extracted.push({
+			chunk_id: r.chunk_id,
+			names: await this.extractRowEntities(r.text)
+		});
+		this.chunks.replaceEntities(extracted, false);
+	}
+	/**
+	* The per-row primitive of the shared entity sweep (`store/entity_sweep.ts`).
+	*
+	* Replaces ONE chunk's entity rows and stamps that same row with `ENTITY_EXTRACTOR_VERSION`, in one
+	* transaction. Knowledge's domain difference from memory is exactly this: memory's transaction also
+	* moves triples, the HRR bundle and the conflict queue, while a chunk has none of those — its
+	* derived state is the entity names alone.
+	*
+	* Per row, not per batch, because the sweep's contract is that a failure leaves THAT row stale and
+	* retryable: inside a batched transaction one bad extraction would roll back the whole batch, and
+	* rows it never reached would look stamped.
+	*/
+	async replaceRowEntities(chunkId, text) {
+		const names = await this.extractRowEntities(text);
+		this.chunks.replaceEntities([{
+			chunk_id: chunkId,
+			names
+		}], true);
+		this.chunks.setEntitiesVersion([chunkId], 1);
 	}
 	/**
 	* Ingest local files/directories. Every path goes through the SAME boundary as
@@ -14330,7 +15409,7 @@ var KnowledgeStore = class {
 		const chunkIds = this.chunks.idsForDoc(docId);
 		const removed = this.docs.remove(docId);
 		if (removed) this.commitCorpus(`remove: ${doc.domain}/${doc.source}/${doc.title}`);
-		this.evictVectors(chunkIds);
+		evictVectors(this.vstore, chunkIds);
 		return removed;
 	}
 	/**
@@ -14522,12 +15601,11 @@ var KnowledgeStore = class {
 	async reindex(domain, opts) {
 		const dryRun = opts?.dryRun === true;
 		const space = this.vectorSpace();
-		const rows = this.chunks.corpusState(domain);
-		const staleEntities = rows.filter((r) => r.entities_version !== 1);
-		const staleVectors = rows.filter((r) => !this.vectorReusable(r, space));
+		const corpus = this.chunks.corpusState(domain);
+		const staleVectors = corpus.filter((r) => !this.vectorReusable(r, space));
 		const semanticAvailable = this.semantic.isAvailable();
 		const report = {
-			chunks: rows.length,
+			chunks: corpus.length,
 			entities_rebuilt: 0,
 			vectors_stale: staleVectors.length,
 			vectors_encoded: 0,
@@ -14536,11 +15614,19 @@ var KnowledgeStore = class {
 		};
 		if (dryRun) return report;
 		this.chunks.rebuildFts();
-		if (staleEntities.length) {
-			await this.replaceChunkEntities(staleEntities, true);
-			this.chunks.setEntitiesVersion(staleEntities.map((r) => r.chunk_id), 1);
-			report.entities_rebuilt = staleEntities.length;
-		}
+		report.entities_rebuilt = (await sweepVersionedEntities({
+			staleEntityBatch: (limit) => ({
+				total: this.chunks.countStaleEntityChunks(1, domain),
+				rows: this.chunks.chunkEntityRows(1, limit, domain)
+			}),
+			staleEntityCount: () => this.chunks.countStaleEntityChunks(1, domain),
+			extractAndWriteEntities: async (row) => {
+				await this.replaceRowEntities(row.chunk_id, row.text);
+			},
+			onRowError: (row, error) => {
+				retrievalLogger().warn(`kb entity sweep: chunk ${String(row.chunk_id)} could not be rebuilt (${error instanceof Error ? error.message : String(error)}) — it keeps its old stamp; the next reindex retries it`);
+			}
+		}, this.entitySweepGuard, { budget: this.chunks.countStaleEntityChunks(1, domain) })).rebuilt;
 		if (!semanticAvailable) this.semantic.ensureWarm?.();
 		else if (staleVectors.length) report.vectors_encoded = (await this.encodeAndStore(staleVectors, space)).encoded;
 		return report;
@@ -14556,18 +15642,7 @@ var KnowledgeStore = class {
 	}
 	/** Chunk search over the knowledge corpus (semantic + FTS + entity, joint fusion). */
 	async search(query, opts) {
-		const result = await hybridSearch(this.hybridDeps(opts), {
-			query,
-			limit: opts?.limit,
-			overFetch: opts?.overFetch,
-			maxTokens: opts?.maxTokens,
-			queryVector: opts?.queryVector,
-			recordStats: opts?.recordStats,
-			floors: opts?.floors,
-			...opts?.includeScores === void 0 ? {} : { includeScores: opts.includeScores },
-			...opts?.relaxLegs === void 0 ? {} : { relaxLegs: opts.relaxLegs },
-			...opts?.rewriteQuery === void 0 ? {} : { rewriteQuery: opts.rewriteQuery }
-		});
+		const result = await runHybridSearch(this.hybridDeps(opts), query, opts);
 		opts?.onResult?.(result);
 		return result.hits;
 	}
@@ -14583,10 +15658,7 @@ var KnowledgeStore = class {
 	*/
 	hybridDeps(opts) {
 		const rowsById = /* @__PURE__ */ new Map();
-		return {
-			kind: "knowledge",
-			config: this.config,
-			semantic: this.semantic,
+		return makeHybridDeps("knowledge", this.config, this.semantic, {
 			legs: (ctx) => this.searchLegs(opts, ctx),
 			texts: (ids) => {
 				rowsById.clear();
@@ -14612,7 +15684,7 @@ var KnowledgeStore = class {
 					}];
 				});
 			}
-		};
+		});
 	}
 	/**
 	* The knowledge legs: semantic, FTS, and entity overlap against the entities extracted AT INGEST
@@ -14622,40 +15694,12 @@ var KnowledgeStore = class {
 	* matching corpus only makes `fuse` normalize and sort it (see `MemoryStore.searchLegs`).
 	*/
 	async searchLegs(opts, ctx) {
-		/**
-		* Wrap one leg's floored scores. `raw` is the PRE-floor set: `capped` must be measured there,
-		* because the relevance floor removes the tail anyway and re-deriving the flag afterwards would
-		* erase the "cut at legCap" signal exactly when it bound.
-		*/
-		const leg = (scores, weight, name, dropped, raw) => ({
-			weight,
-			scores,
-			capped: (raw ?? scores).size === ctx.legCap,
-			leg: name,
-			droppedByFloor: dropped
-		});
+		const runner = makeLegRunner(ctx);
 		const ftsRaw = this.ftsPath(ctx.query, opts?.domain, opts?.source, ctx.legCap);
-		const ftsFloored = applyTermFloor(ftsRaw, this.chunkTexts([...ftsRaw.keys()]), ctx.query, ctx.floors.fts);
 		return [
-			ctx.semAvail ? this.semanticPath(ctx.query, ctx.overFetch, opts, ctx.queryVector, ctx.onQueryVector).then((raw) => {
-				const floored = applyScoreFloor(raw, ctx.floors.semantic);
-				return {
-					weight: ctx.weights.semantic,
-					scores: floored.scores,
-					leg: "semantic",
-					droppedByFloor: floored.dropped
-				};
-			}) : {
-				weight: ctx.weights.semantic,
-				scores: /* @__PURE__ */ new Map(),
-				leg: "semantic",
-				droppedByFloor: 0
-			},
-			leg(ftsFloored.scores, ctx.weights.fts, "fts", ftsFloored.dropped, ftsRaw),
-			this.jaccardPath(ctx.query, opts?.domain, opts?.source, ctx.legCap).then((raw) => {
-				const floored = applyScoreFloor(raw, ctx.floors.jaccard);
-				return leg(floored.scores, ctx.weights.jaccard, "jaccard", floored.dropped, raw);
-			})
+			ctx.semAvail ? this.semanticPath(ctx.query, ctx.overFetch, opts, ctx.queryVector, ctx.onQueryVector).then((raw) => runner.semantic(raw, ctx.weights.semantic, ctx.floors.semantic)) : runner.semanticOff(ctx.weights.semantic),
+			runner.term("fts", ftsRaw, this.chunkTexts([...ftsRaw.keys()]), ctx.query, ctx.weights.fts, ctx.floors.fts),
+			this.jaccardPath(ctx.query, opts?.domain, opts?.source, ctx.legCap).then((raw) => runner.scored("jaccard", raw, ctx.weights.jaccard, ctx.floors.jaccard))
 		];
 	}
 	/** The texts of a candidate set, for the per-row FTS floor (one batched query). */
@@ -14670,43 +15714,55 @@ var KnowledgeStore = class {
 	* re-encoding (performance review §7.7 / P8).
 	*/
 	async semanticPath(query, k, opts, queryVector, onVector) {
-		const vec = queryVector ?? await this.semantic.encode(query);
-		if (vec.length !== this.vstore.dim) throw new RetrievalInputError(`queryVector 维度不符：${vec.length} != ${this.vstore.dim}`);
-		onVector?.(vec);
-		const topk = this.vstore.topk(vec, Math.max(50, k));
-		if (!topk.length) return /* @__PURE__ */ new Map();
-		if (!opts?.domain && !opts?.source) return new Map(topk.map((t) => [t.id, t.score]));
-		const meta = new Map(this.chunks.meta(topk.map((t) => t.id)).map((r) => [r.chunk_id, r]));
-		const out = /* @__PURE__ */ new Map();
-		for (const t of topk) {
-			const r = meta.get(t.id);
+		return semanticLeg({
+			query,
+			k,
+			queryVector,
+			onVector,
+			encode: (q) => this.semantic.encode(q),
+			dim: this.vstore.dim,
+			topk: (vec, n) => this.vstore.topk(vec, n),
+			filterTopk: (ids) => this.scopeFilter(ids, opts)
+		});
+	}
+	/**
+	* The semantic leg's scope filter, as a `filterTopk` primitive: `undefined` when NO domain/source
+	* was asked means "keep the whole pool" — the short-circuit is preserved, so no `chunks.meta`
+	* lookup runs at all. Otherwise one batched lookup, and rows whose domain/source do not match (or
+	* whose chunk is gone) are dropped.
+	*/
+	scopeFilter(ids, opts) {
+		if (!opts?.domain && !opts?.source) return void 0;
+		const meta = new Map(this.chunks.meta(ids).map((r) => [r.chunk_id, r]));
+		const keep = /* @__PURE__ */ new Set();
+		for (const id of ids) {
+			const r = meta.get(id);
 			if (!r) continue;
 			if (opts.domain && r.domain !== opts.domain) continue;
 			if (opts.source && r.source !== opts.source) continue;
-			out.set(t.id, t.score);
+			keep.add(id);
 		}
-		return out;
+		return keep;
 	}
 	/**
 	* Sync relevance probe for the plugin's conditional hint (DESIGN §12). Same contract as
 	* `MemoryStore.lexicalProbe` — see `store/lexical.ts`.
 	*/
 	lexicalProbe(text, stopAt = Number.POSITIVE_INFINITY) {
-		return probeTerms(text, (term) => {
-			const fts = buildFtsQuery(term, this.ftsTokenizer);
-			return fts !== null && this.chunks.ftsSearch(fts, void 0, void 0, 1).length > 0;
-		}, stopAt);
+		return probeStoreTerms(text, this.ftsTokenizer, (fts) => this.chunks.ftsSearch(fts, void 0, void 0, 1).length > 0, stopAt);
 	}
 	ftsPath(query, domain, source, cap) {
-		const ftsQuery = buildFtsQuery(query, this.ftsTokenizer);
-		if (ftsQuery) {
-			const rows = this.chunks.ftsSearch(ftsQuery, domain, source, cap);
-			return new Map(rows.map((r) => [r.id, -r.rank]));
-		}
-		const terms = substringTerms(query);
-		if (terms.length === 0) return /* @__PURE__ */ new Map();
-		const rows = this.chunks.ftsSubstringSearch(terms, domain, source, cap);
-		return new Map(rows.map((r) => [r.id, r.rank]));
+		return ftsLeg({
+			query,
+			cap,
+			scope: {
+				domain,
+				source
+			},
+			tokenizer: this.ftsTokenizer,
+			search: (ftsQuery, scope, limit) => this.chunks.ftsSearch(ftsQuery, scope.domain, scope.source, limit),
+			substringSearch: (terms, scope, limit) => this.chunks.ftsSubstringSearch(terms, scope.domain, scope.source, limit)
+		});
 	}
 	/**
 	* Entity overlap against entities extracted AT INGEST time (chunk_entities) — no corpus scan.
@@ -15079,7 +16135,13 @@ function buildRuntime(opts) {
 				case "contradict_resolve": return this.memory.resolveContradiction(req.contradiction_id, req.resolution, req.loser_fact_id);
 				case "maintenance": return this.memory.maintenance();
 				case "vectors_diagnose": return this.memory.vectorsDiagnose();
-				case "vectors_fix": return this.memory.vectorsFix(req.dry_run ?? false);
+				case "vectors_fix": return vectorsFix({
+					memory: this.memory.vectorRepairTarget(),
+					knowledge: this.knowledge.vectorRepairTarget()
+				}, {
+					dryRun: req.dry_run ?? false,
+					...req.store === void 0 ? {} : { store: req.store }
+				});
 				default: return { error: `admin.${req.action} not implemented` };
 			}
 		},
@@ -15331,6 +16393,7 @@ const descriptors = [
 		offset: count.optional(),
 		reason: optionalText.optional(),
 		dry_run: bool.optional(),
+		store: optionalText.optional(),
 		contradiction_id: count.optional(),
 		resolution: optionalText.optional(),
 		loser_fact_id: count.optional()
@@ -15593,6 +16656,12 @@ function cannotDetermine(error, log, prefix) {
 * Run the gate. Call this FIRST in `apply()`: on a refusal nothing has been registered yet, so
 * "do not load" costs nothing to unwind. Never throws — not even with a throwing logger, because
 * "cannot tell" is not "incompatible".
+*
+* The check itself is the BASE's `provision` (gather + verdict + logging, one call). The local
+* fallback stays on purpose (option A): the interface-generation axis cannot gate this dependency
+* (same-generation bases never read as `incompatible`), and raising the peer floor would degrade
+* every host on a base that predates the fix — so a `provision` that cannot be performed still
+* leaves the plugin loading.
 * @param ctx - the plugin's context.
 * @param log - the plugin's logger.
 * @param compat - the loaded gate runtime (see `src/envinit.ts`).
@@ -15601,22 +16670,11 @@ function cannotDetermine(error, log, prefix) {
 * @returns the verdict `apply` branches on.
 */
 function provision(ctx, log, compat, spec = compat.spec) {
-	let evidence;
-	try {
-		evidence = compat.module.gatherEvidence(ctx, spec);
-	} catch (error) {
-		return cannotDetermine(error, log, compat.prefix);
-	}
-	let verdict;
 	try {
-		verdict = compat.module.verdictOf(evidence);
+		return { verdict: compat.module.provision(ctx, log, spec) };
 	} catch (error) {
 		return cannotDetermine(error, log, compat.prefix);
 	}
-	for (const line of verdict.lines) try {
-		log[line.level](line.message);
-	} catch {}
-	return { verdict };
 }
 /**
 * Keep one `/mem` command that reports a refusal.
@@ -16062,83 +17120,6 @@ function rangeOf(value) {
 	return typeof range === "string" && range.trim() !== "" ? range : void 0;
 }
 //#endregion
-//#region lib/types/interface_gate.js
-/** Read one member without letting a hostile module's getter escape. */
-function member(module, name) {
-	try {
-		return module?.[name];
-	} catch {
-		return;
-	}
-}
-function cannotTell(reason) {
-	return {
-		status: "cannot-tell",
-		reason
-	};
-}
-/**
-* Whether the base's shared capabilities may be used under `verdict`.
-*
-* The ONE mapping from the gate's verdict to the loader's decision, exported so it is asserted
-* directly and the loader and its test cannot drift: only `incompatible` withholds the base;
-* `cannot-tell` does not, because it is not a negative answer. A `false` here is still a DEGRADATION
-* (own prompt defaults, gate skipped, legacy provisioning), never a refused mount.
-*/
-function baseIsUsable(verdict) {
-	return verdict.status !== "incompatible";
-}
-/**
-* Where the build's bake record sits when no explicit URL is given: beside the built ENTRY
-* (`lib/index.js`), which is where `scripts/link-envinit.mjs` writes it. A per-file `tsc` emit of
-* this module lives one directory below that entry and looks one level up; the first readable record
-* wins. Under `vitest` (running from `src/`) neither exists, which is the correct "not baked".
-*/
-const BAKED_CANDIDATES = ["./interface-version.json", "../interface-version.json"];
-/**
-* Read this artifact's baked requirement through the loaded base's own reader.
-* @param read - the base's `readInterfaceRequirement`, taken off the loaded module.
-* @param bakedUrl - test seam: read EXACTLY this record instead of walking {@link BAKED_CANDIDATES}.
-*/
-function requirementOf(read, bakedUrl) {
-	const candidates = bakedUrl === void 0 ? BAKED_CANDIDATES.map((relative) => new URL(relative, import.meta.url)) : [bakedUrl];
-	for (const url of candidates) {
-		let requirement;
-		try {
-			requirement = read(url);
-		} catch {
-			continue;
-		}
-		const version = requirement?.interfaceVersion;
-		if (typeof version === "number" && Number.isInteger(version) && version > 0) return { interfaceVersion: version };
-	}
-}
-/**
-* Ask the loaded base whether it implements the interface generation this artifact was built for.
-*
-* @param module - the loaded base module (only `checkInterface` / `readInterfaceRequirement` are
-*   touched, each through a guarded read).
-* @param bakedUrl - test seam: the bake record to read; production leaves it undefined.
-* @returns a verdict that is never `incompatible` unless BOTH sides were readable and differ, and
-*   never a throw.
-*/
-function interfaceVerdict(module, bakedUrl) {
-	const check = member(module, "checkInterface");
-	const read = member(module, "readInterfaceRequirement");
-	if (typeof check !== "function" || typeof read !== "function") return cannotTell("the loaded base has no interface gate (checkInterface / readInterfaceRequirement missing) — it predates the runtime interface contract, so which generation it implements cannot be told");
-	const requirement = requirementOf(read, bakedUrl);
-	if (requirement === void 0) return cannotTell("this build has no baked interface requirement (lib/interface-version.json is missing or malformed), so the runtime interface gate cannot run");
-	let verdict;
-	try {
-		verdict = check(requirement.interfaceVersion, module);
-	} catch {
-		return cannotTell("the loaded base threw while judging the interface generation");
-	}
-	const status = verdict?.status;
-	if (status !== "ok" && status !== "incompatible" && status !== "cannot-tell") return cannotTell("the loaded base returned no usable interface verdict");
-	return verdict;
-}
-//#endregion
 //#region lib/types/envinit.js
 /**
 * Environment initialisation for the memory plugin, through the family base
@@ -16398,8 +17379,22 @@ function modelItem(framework, model) {
 		policy: { timeoutMs: MODEL_REQUEST_TIMEOUT_MS }
 	};
 }
-let loaded;
-let loading;
+/**
+* The plugin-specific halves of the shared loader's sentences: mem says the FRAMEWORK is skipped and
+* names the legacy provisioning path among the withheld capabilities. The mechanism is the shim's
+* (`interface_gate.ts`), the wording is this plugin's.
+*/
+const DEGRADE_WORDS = {
+	prefix: OWN_PREFIX,
+	loadFailure: "the framework is SKIPPED and the plugin will mount anyway",
+	withheld: "own prompt defaults, gate skipped, legacy provisioning"
+};
+/**
+* The loaded runtime, cached once per process through the shared cache discipline: a FAILED load is
+* NOT cached, so a profile reload retries instead of replaying the first failure for the whole
+* process lifetime.
+*/
+const cache = createLoadCache((options) => loadGuarded(options, loadOnce, options.log, DEGRADE_WORDS));
 /**
 * Ensure the framework, then the compatibility base, then dispatch the expensive resources.
 *
@@ -16409,32 +17404,11 @@ let loading;
 * base still returns a runtime, with `compat: undefined`: the mount must continue, and the resource
 * items are still worth dispatching.
 *
-* The result is cached per process; a FAILED load is not, so a profile reload retries instead of
-* replaying the first failure for the whole process lifetime.
-*
 * @param options - logger, family root, download policy and the test seams.
 * @returns the loaded runtime, or `undefined` when the framework itself is unavailable.
 */
-async function loadEnvinit(options = {}) {
-	if (loaded !== void 0) return loaded;
-	if (loading !== void 0) return loading;
-	loading = loadGuarded(options).then((runtime) => {
-		if (runtime === void 0) loading = void 0;
-		else loaded = runtime;
-		return runtime;
-	}, () => {
-		loading = void 0;
-	});
-	return loading;
-}
-/** The guard that makes "never throws" true: every failure is a warning plus `undefined`. */
-async function loadGuarded(options) {
-	try {
-		return await loadOnce(options);
-	} catch (error) {
-		warn(options.log, `${OWN_PREFIX} WARNING — environment initialisation failed (${reasonOf(error)}); the framework is SKIPPED and the plugin will mount anyway`);
-		return;
-	}
+function loadEnvinit(options = {}) {
+	return cache.load(options);
 }
 /** The body of {@link loadEnvinit}; the cache above makes it run at most once per process. */
 async function loadOnce(options) {
@@ -16454,14 +17428,7 @@ async function loadOnce(options) {
 		warn(options.log, `${OWN_PREFIX} WARNING — ${FRAMEWORK_PACKAGE} could not be made available; the plugin falls back to its own provisioning and mounts anyway`);
 		return;
 	}
-	{
-		const verdict = interfaceVerdict(framework);
-		if (!baseIsUsable(verdict)) {
-			warn(options.log, `${OWN_PREFIX} WARNING — interface: ${verdict.reason ?? "the loaded base implements another interface generation"}; the base's shared capabilities are NOT used (own prompt defaults, gate skipped, legacy provisioning) and the plugin mounts anyway`);
-			return;
-		}
-		if (verdict.status === "cannot-tell") warn(options.log, `${OWN_PREFIX} WARNING — interface: ${verdict.reason ?? "the interface generation cannot be told"}; using the loaded base anyway ("cannot tell" is never "incompatible")`);
-	}
+	if (!gateOrDegrade(framework, options.log, DEGRADE_WORDS)) return void 0;
 	const disposers = [];
 	let compat;
 	try {
@@ -16521,8 +17488,7 @@ async function loadOnce(options) {
 			for (const instance of disposers.splice(0)) try {
 				instance.dispose();
 			} catch {}
-			loaded = void 0;
-			loading = void 0;
+			cache.clear();
 		}
 	};
 }
@@ -16772,37 +17738,43 @@ function openDocumentPath(documentPath, target, configured, deps = {}) {
 }
 //#endregion
 //#region lib/types/vectorMigration.js
+/**
+* The plugin's lifecycle for the bounded, resumable background migration of persisted vectors into
+* the current embedding space.
+*
+* Changing the embedding space (default model, width, pooling, normalization, input window, weights)
+* is a DATA MIGRATION, not a config tweak: every persisted vector still decodes, but in another
+* model's coordinates, so the semantic leg must not serve it. Measured on the real library after the
+* 512→768 default-model swap, 78 of 80 ACTIVE facts fell out of the semantic leg and retrieval
+* degraded to lexical+entity with no error anywhere — the stores' open-time warning now says so, and
+* this module is what repairs it without the operator having to know `vectors --fix` exists.
+*
+* The FLOW lives in the engine, once, for both stores (`@avantf/mem`'s `store/vector_repair.ts`:
+* batch size, event-loop yield, stop / resume / no-progress rules, the `semantic.auto_migrate`
+* decision and the four store-named log kinds). It is driven for BOTH stores — memory and knowledge
+* — in one pass, because one embedding space is configured for the whole runtime: the knowledge
+* store used to be left behind, silently, with only a manual `kb_reindex` able to fix it.
+*
+* This module owns only the process LIFECYCLE: one start, one stop, and "never an unhandled
+* rejection". It sits BEHIND the startup gate (`awaitStartupGate`, see index.ts): the model warm and
+* this first batch must not land in the boot window (DESIGN §20.14).
+*
+* Deliberately no state: what still needs migrating is derived from the databases on every pass —
+* and the adapters are created ONCE so the shared flow's once-per-process `auto_migrate` warning is
+* genuinely once per process, not once per heartbeat.
+*/
 function createVectorMigration(opts) {
 	const { rt, logger } = opts;
+	const targets = [rt.memory.vectorRepairTarget(), rt.knowledge.vectorRepairTarget()];
 	let running = false;
 	let stopped = false;
-	let warnedDisabled = false;
 	const run = async () => {
-		const health = rt.memory.vectorSpaceHealth();
-		const pending = health.stale + health.space_stale;
-		if (pending === 0) return;
 		if (rt.closed || !opts.isActive()) return;
-		if (rt.config.common.semantic.auto_migrate === false) {
-			if (!warnedDisabled) {
-				warnedDisabled = true;
-				logger.warn(`vector migration: ${String(pending)} ACTIVE vector(s) belong to an older embedding space and \`semantic.auto_migrate\` is off — the semantic leg stays blind to them; run \`avantf-mem vectors --fix\` (MCP/plugin: \`mem_admin vectors_fix\`) or set \`semantic.auto_migrate: true\``);
-			}
-			return;
-		}
-		const startedAt = Date.now();
-		logger.info(`vector migration: ${String(pending)} ACTIVE vector(s) belong to an older embedding space (${String(health.space_stale)} same-width, another representation, ${String(health.stale)} wrong-width) — re-encoding in the background (a representation change — model, pooling, normalization, input window or weights — migrates the whole corpus once)`);
-		const outcome = await rt.memory.migrateVectors({
+		await driveVectorRepairs(targets, {
 			...opts.batchSize === void 0 ? {} : { batchSize: opts.batchSize },
 			shouldStop: () => stopped || rt.closed || !opts.isActive(),
-			onProgress: (progress) => {
-				logger.info(`vector migration: re-encoded ${String(progress.migrated)}/${String(pending)} (${String(progress.remaining)} left)`);
-			}
+			log: logger
 		});
-		if (outcome.remaining === 0) {
-			logger.info(`vector migration: complete — ${String(outcome.migrated)} vector(s) re-encoded in ${String(Date.now() - startedAt)}ms; the semantic leg is current`);
-			return;
-		}
-		if (!stopped && !rt.closed && opts.isActive()) logger.warn(`vector migration: ${String(outcome.remaining)} vector(s) still belong to an older embedding space (the embedding model may be unavailable) — the next heartbeat retries; manual entry \`avantf-mem vectors --fix\``);
 	};
 	return {
 		start() {
@@ -17067,15 +18039,7 @@ const ENTITY_SWEEP_PER_HEARTBEAT = 2e3;
 /** Minimum spacing between corpus drift checks (`tools/result` fires for EVERY tool). */
 const RECONCILE_MIN_INTERVAL_MS = 2e3;
 async function runToolSpec(spec, rt, args) {
-	const parsed = spec.input.safeParse(args ?? {});
-	if (!parsed.success) return validationError(spec.name, parsed.error.issues);
-	if (!supportsToolKey(spec.key)) return toolErr(`unknown tool ${spec.key}`);
-	try {
-		const value = await dispatchToolKey(rt, spec.key, parsed.data);
-		return toolOk(modelFacingToolResult(spec.key, parsed.data.action, value));
-	} catch (error) {
-		return toolErr(error);
-	}
+	return await runToolSpec$1(rt, spec, args);
 }
 function present(spec, args) {
 	return {
@@ -17429,19 +18393,6 @@ function hostLogger(ctx) {
 	};
 }
 /**
-* Whether this plugin's fiber is still alive after the environment await.
-*
-* The environment gate can take the whole startup budget (15 s on a first run) and the framework may
-* even fetch the gate's base during it. A profile reload or unload landing inside that window clears
-* the fiber's uid, after which every Cordis call throws `INACTIVE_EFFECT` — the plugin would then
-* half-register (the Remote face cannot be rolled back) instead of stopping cleanly. An unknown
-* shape is "cannot tell", so only an explicitly cleared uid counts as disposed.
-*/
-function stillActive(ctx) {
-	const fiber = ctx.fiber;
-	return fiber === void 0 || fiber.uid !== null;
-}
-/**
 * Declare the expensive resources through the family framework, warm the tokenizer and the embedding
 * model, and continue initialisation as each item settles.
 *
@@ -17597,19 +18548,18 @@ async function apply(ctx, config) {
 	});
 	const heartbeatMinutes = rt.config.common.trust.presence.heartbeat_minutes;
 	if (heartbeatMinutes > 0) ctx.effect(() => {
-		const timer = setInterval(() => {
-			try {
-				rt.memory.trustTick();
-			} catch (error) {
-				logger.warn(`trust tick failed: ${error instanceof Error ? error.message : String(error)}`);
-			}
-			sweepEntities();
-			vectorMigration.start();
-		}, heartbeatMinutes * 6e4);
-		const unref = timer.unref;
-		if (typeof unref === "function") unref.call(timer);
+		const stop = installTrustHeartbeat({
+			memory: rt.memory,
+			logger,
+			heartbeatMinutes,
+			onBeat: () => {
+				sweepEntities();
+				vectorMigration.start();
+			},
+			tickFailed: (message) => `trust tick failed: ${message}`
+		});
 		logger.info(`trust heartbeat: every ${heartbeatMinutes}min (active-day clock + lifecycle sweep)`);
-		return () => clearInterval(timer);
+		return stop;
 	});
 	const promptDir = join(rt.config.home, "prompts");
 	const kit = env?.kit;