@avantf/dsh-mem 0.6.3 → 0.6.4

package/lib/engine/mem/db/dao/chunks.d.ts

@@ -115,6 +115,12 @@ export declare class ChunksDao {
      * 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).
+     *
+     * The JS rule itself is `store/vector_space.ts` (`classifyVectorSpace` / `countVectorSpace`), and
+     * this projection is bound to it by the cross assertions in
+     * `test/knowledge_vector_migration.spec.ts` (the startup warning's count, the health count and the
+     * migration's `remaining` all have to be the same number). NOTHING here changes when the JS rule
+     * changes: the mirror is checked, not shared.
      */
     vectorSpaceCounts(space: string, expectedBytes: number): {
         stale: number;

package/lib/engine/mem/db/dao/fact_sources.d.ts

@@ -8,10 +8,28 @@
  * The SQL lives here like every other aggregate. The store decides WHICH source a write carries
  * (and refuses to invent one when the caller gave none); the DAO only records and reads rows.
  */
+import type { FactSourceView } from '../../../mem-contract/index.js';
 import type { Db } from '../port.js';
-/** The closed `kind` vocabulary, spelled once so the store and the tests share it. */
+/**
+ * The kind axis is the CONTRACT's, not a second list: `FactSourceView['kind']` is what `admin detail`
+ * renders and what the writer below records, so deriving the type from it is what makes "the closed
+ * vocabulary" one thing. (Before, the array here and the union in `types.ts` were two independent
+ * spellings that happened to agree.)
+ */
+export type FactSourceKind = FactSourceView['kind'];
+/**
+ * The closed `kind` vocabulary, spelled once so the store and the tests share it.
+ *
+ * The `satisfies` pins every member to the contract's union; the `Exclude` below pins the other
+ * direction, so a kind the contract ADDS fails to compile here instead of silently never being
+ * recorded.
+ */
 export declare const FACT_SOURCE_KINDS: readonly ["session", "kb_doc", "tool", "manual"];
-export type FactSourceKind = (typeof FACT_SOURCE_KINDS)[number];
+/**
+ * The FALLBACK kind: a `source_ref` without a recognized `kind:` prefix is `manual` with the
+ * reference kept VERBATIM (the tool contract says so, and "no shape guessing" is the point).
+ */
+export declare const FACT_SOURCE_FALLBACK_KIND: "manual";
 /** One provenance row as the read surfaces render it. */
 export interface FactSource {
     kind: FactSourceKind;
@@ -21,10 +39,14 @@ export interface FactSource {
  * Derive `(kind, ref)` from the single `source_ref` the write face accepts.
  *
  * The tool takes ONE string (the plan adds no second parameter), so the kind axis is spelled by a
- * `kind:` prefix — `session:…` / `kb_doc:…` / `tool:…` — and anything else is `manual` with the
- * reference kept VERBATIM. No shape guessing: a bare `domain:source:title` becomes a `manual`
- * source whose ref is exactly what the caller wrote, which is strictly more honest than inventing
- * a category from how the string looks.
+ * `kind:` prefix — `session:…` / `kb_doc:…` / `tool:…` — and anything else, INCLUDING the fallback
+ * kind's own name, is `manual` with the reference kept VERBATIM. No shape guessing: a bare
+ * `domain:source:title` becomes a `manual` source whose ref is exactly what the caller wrote, which
+ * is strictly more honest than inventing a category from how the string looks.
+ *
+ * The prefix table comes from {@link FACT_SOURCE_KINDS} (see {@link FACT_SOURCE_PREFIX_KINDS}) rather
+ * than from a hand-written alternation, which is what keeps the recognized set and the recorded set
+ * from being two lists.
  */
 export declare function classifySourceRef(sourceRef: string): {
     kind: FactSourceKind;

package/lib/engine/mem/defaults.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The two page/result defaults the engine falls back to when neither the caller nor the config says
+ * anything — spelled ONCE, because each of them used to be written in two or three places.
+ *
+ * They are the ENGINE's consumption points of numbers the CONTRACT documents:
+ *
+ *   - `DEFAULT_SEARCH_LIMIT` — `query`'s own input schema carries `.default(10)`
+ *     (`contract/src/tools.ts`), and the recall actions' descriptions say "默认 10"; the recall union
+ *     itself is `.optional()`, so the engine is what applies it. It reaches `hybridSearch` (a
+ *     non-finite limit) and the cross-store router.
+ *   - `DEFAULT_LIST_LIMIT` — the documented page for `admin list` and `kb_list` ("默认 50" /
+ *     "缺省 50", same file).
+ *
+ * The cross-layer equation is pinned by `test/hybrid.spec.ts` against the contract's parsed schema,
+ * so a contract default moving and this constant not moving is a red test rather than a silent
+ * off-by-page behaviour. (These live here rather than in the contract because `@avantf/mem-contract`
+ * is consumed as built output: a constant added there is only visible to this engine after the
+ * contract is rebuilt, which a source-only change may not assume.)
+ *
+ * @module defaults
+ */
+/** Page of a recall/query result when the caller gave no usable `limit`. */
+export declare const DEFAULT_SEARCH_LIMIT = 10;
+/** Page of a listing surface (`admin list`, `kb_list`) when the caller gave no `limit`. */
+export declare const DEFAULT_LIST_LIMIT = 50;

package/lib/engine/mem/dispatch.d.ts

@@ -16,10 +16,12 @@
 import type { KbAddRequest, ToolEnvelope, ToolSpec } from '../mem-contract/index.js';
 import type { AvantfRuntime } from './runtime.js';
 /**
- * The default page for a model-facing `kb_list`.
+ * The default page for a model-facing `kb_list` — the SAME page the operator's `admin list` uses.
  *
  * Without one, `kb_list` on a large library read and parsed EVERY managed file (resolving a path
- * needs the file's frontmatter to detect collisions) to answer a question nobody asked in full.
+ * needs the file's frontmatter to detect collisions) to answer a question nobody asked in full. The
+ * two surfaces were separate literals; the contract documents both as 50, so they are one constant
+ * (`src/defaults.ts`).
  */
 export declare const KB_LIST_DEFAULT_LIMIT = 50;
 /**

package/lib/engine/mem/modelBootstrap.d.ts

@@ -55,22 +55,6 @@ export interface WarmOptions {
  *   path keeps it, because there the caller only sees this logger.
  */
 export declare function warmModels(rt: AvantfRuntime, options?: WarmOptions, reportFinal?: boolean): Promise<boolean>;
-/**
- * Warm ONLY the embedding model: load it from `semantic.cache_dir` and mark the engine ready.
- *
- * Split out of {@link warmModels} for the plugin's envinit path. There the framework fetches the
- * model in the BACKGROUND, so the warm has to wait for the item to settle instead of running at
- * mount — and the runtime's own constructor warm is deferred for exactly that reason
- * (`RuntimeOptions.managedRoots` → `deferWarm`), which is what stops it racing the install and
- * leaving a second copy behind. While the item is unsettled NOTHING warms; this function is the
- * explicit "files are there now, look" step, and it still runs when the item skipped/failed so
- * `semantic.auto_download` can decide between the runtime's own fetch and degradation.
- *
- * @param rt - the runtime whose memory store owns the semantic backend.
- * @param reportFinal - log the one-line verdict (default `true`).
- * @returns whether the semantic path is available.
- */
-export declare function warmSemantic(rt: AvantfRuntime, reportFinal?: boolean): Promise<boolean>;
 /**
  * Wait out the startup gate — the host readiness signal (bounded by {@link WAIT_FOR_HOST_MS}) and,
  * when asked, one quiet turn of the event loop.
@@ -88,18 +72,6 @@ export declare function warmSemantic(rt: AvantfRuntime, reportFinal?: boolean):
  * @returns how long the idle gate waited (ms), or `0` when it was not requested.
  */
 export declare function awaitStartupGate(options?: WarmOptions): Promise<number>;
-/**
- * Warm ONLY the tokenizer, after the host-readiness signal and (when asked) an idle event loop.
- *
- * nodejieba loads its dictionary lazily on the FIRST `tag()` (measured ~950 ms, after which a call
- * is 0.1 ms), so without this the first write/query of a session pays it while the user waits. Its
- * cost belongs to startup, and an unavailable jieba is worth saying out loud — entity extraction
- * silently degrades to the regex fallback (weaker entity/jaccard legs).
- *
- * @param rt - the runtime whose logger reports the outcome.
- * @param options - the host-readiness signal and the idle gate (see {@link WarmOptions}).
- */
-export declare function warmTokenizer(rt: AvantfRuntime, options?: WarmOptions): Promise<void>;
 /**
  * Non-blocking embedding warm, for a caller that knows the model files are already on disk.
  *
@@ -160,48 +132,7 @@ export interface ProvisionSweepResult {
  * @returns whether the sweep ran or was skipped for incompatibility.
  */
 export declare function provisionToolchainAsync(rt: AvantfRuntime, options?: ProvisionSweepOptions): Promise<ProvisionSweepResult>;
-/** The artifact id, used in the startup log and in the model artifact's errors. */
-export declare const MODEL_ARTIFACT_ID = "model";
 /** The environment a model-artifact call runs under: the runtime that owns the model cache. */
 export interface ModelArtifactEnv {
     runtime: AvantfRuntime;
 }
-/** The slice of an artifact call this module needs (`@avantf/mem-provision`'s InstallContext). */
-interface ModelInstallContext {
-    logger: {
-        info(message: string): void;
-        warn(message: string): void;
-        error(message: string): void;
-    };
-    artifactEnv?: unknown;
-    config: {
-        auto_install: boolean;
-    };
-}
-/**
- * The embedding model (plus the nodejieba tokenizer it shares its warm-up budget with) as an
- * ARTIFACT, so the startup sweep in `@avantf/mem-provision` is the only initialization path.
- *
- * It used to be a parallel model warm-up call beside the tools sweep, which meant two
- * startup mechanisms with two logging vocabularies and no single place that answered "is this host
- * fully provisioned?". The model has no pinned version and no managed directory of its own ON THIS
- * (the flat `<repo>/<file>` layout the transformers.js cache reads), so it
- * declares neither; its `isPresent` is `false` because "is the model warm?" is not a question that
- * can be answered without attempting the warm-up, and the warm-up is cheap when the cache is
- * already there (measured ~1.2 s, in the background). The DSH plugin uses this sweep only when the
- * family framework is unavailable — with the framework up, `mem:model` owns the model root instead
- * and this artifact is not registered.
- */
-export declare const modelArtifact: {
-    id: string;
-    title: string;
-    verb: string;
-    isPresent(): Promise<boolean>;
-    install(ctx: ModelInstallContext): Promise<void>;
-    verify(ctx: {
-        logger: ModelInstallContext["logger"];
-    }): Promise<void>;
-};
-/** Register the model artifact once per process (idempotent for a test that mounts twice). */
-export declare function registerModelArtifact(): void;
-export {};

package/lib/engine/mem/store/hybrid.d.ts

@@ -26,8 +26,6 @@
 import { type Config, type FloorProfile, type RecallResult, type RetrievalFloorDrops, type RetrievalFloors } from '../../mem-contract/index.js';
 import { type BudgetInput, type Hit, type SemanticBackend } from '../../mem-retrieval/index.js';
 import { type FloorLeg } from './floors.js';
-/** The `limit` a caller gets when it passes nothing usable. */
-export declare const DEFAULT_SEARCH_LIMIT = 10;
 /**
  * A retrieval input the CALLER got wrong, as opposed to a backend that failed at runtime.
  *
@@ -39,8 +37,6 @@ export declare const DEFAULT_SEARCH_LIMIT = 10;
  */
 export declare class RetrievalInputError extends Error {
 }
-/** …and the over-fetch factor when the config does not set one (matches the contract default). */
-export declare const DEFAULT_OVER_FETCH_FACTOR = 5;
 /** The three weights a `RecallResult` reports. */
 export type RetrievalWeights = RecallResult['weights'];
 /** One retrieval leg's contribution to the fusion. */

package/lib/engine/mem/store/vector_space.d.ts

@@ -0,0 +1,60 @@
+import type { StaleVectorCounts } from './common.js';
+/** What one persisted vector IS, in the current space. */
+export type VectorSpaceVerdict = 'current' | 'stale' | 'space_stale';
+/**
+ * A persisted vector's width, in whichever shape the CALLER already has it — the discriminant is the
+ * shape, never the truth:
+ *
+ *   - `blob` — the raw BLOB (`Uint8Array`), for a caller that has read the bytes;
+ *   - `byteLength` — a projected `length(semantic_vector)`, for a caller that must not read them;
+ *   - `decoded` — an already decoded `Float32Array`, for a caller that had to decode anyway.
+ *
+ * All three answer the same question (`width === dim`), which is the point: the caller with the
+ * cheapest possible evidence is not forced to re-read the row in another shape. A `null`/`undefined`
+ * width is "no usable bytes" and classifies as `stale`, like a wrong one.
+ */
+export type PersistedVectorWidth = {
+    readonly source: 'blob';
+    readonly vec: Uint8Array | null | undefined;
+} | {
+    readonly source: 'byteLength';
+    readonly byteLength: number | null | undefined;
+} | {
+    readonly source: 'decoded';
+    readonly vec: Float32Array | null | undefined;
+};
+/** One width probe plus the space RECORDED beside it (the second element of the rule). */
+export type VectorSpaceProbe = PersistedVectorWidth & {
+    /** `facts.embedding_model` / `doc_chunks.embedding_model` of the same row; `null` = unrecorded. */
+    readonly embeddingModel: string | null | undefined;
+};
+/** The space the store writes into RIGHT NOW. */
+export interface VectorSpaceIdentity {
+    /** The representation fingerprint (`vectorSpaceOf`). */
+    readonly space: string;
+    /** The width the store writes now, in floats. */
+    readonly dim: number;
+}
+/** One row's classification. */
+export interface VectorSpaceClassification {
+    readonly verdict: VectorSpaceVerdict;
+    /** Of a `space_stale` verdict: the recorded id predates the representation fingerprint. */
+    readonly legacy: boolean;
+}
+/**
+ * Classify ONE persisted vector. Pure: no store, no database, no logging — a caller that disagrees
+ * with the result has to disagree with the rule, not with a copy of it.
+ *
+ * A caller-supplied vector is trusted to come from this backend, but its DIMENSION is still checked
+ * — the same asymmetry `legs.ts` applies to a caller-supplied `queryVector`: provenance is the
+ * caller's to assert, width is cheap and decides whether the bytes can be compared at all.
+ */
+export declare function classifyVectorSpace(probe: VectorSpaceProbe, identity: VectorSpaceIdentity): VectorSpaceClassification;
+/**
+ * {@link classifyVectorSpace} over a corpus: the `{ stale, space_stale, legacy }` triple the warning
+ * and the `/mem` status surface report, counted by the same rule that classified each row.
+ *
+ * `legacy` counts only rows already counted in `space_stale` (`reportStaleVectors` clamps it there
+ * too) — it is a REASON split, never a fourth bucket.
+ */
+export declare function countVectorSpace(probes: readonly VectorSpaceProbe[], identity: VectorSpaceIdentity): StaleVectorCounts;

package/lib/index.js

@@ -3777,8 +3777,19 @@ const modelArtifact = {
 };
 /** Register the model artifact once per process (idempotent for a test that mounts twice). */
 function registerModelArtifact() {
-	if (!hasArtifact("model")) registerArtifact(modelArtifact);
+	if (!hasArtifact(MODEL_ARTIFACT_ID)) registerArtifact(modelArtifact);
 }
+//#endregion
+//#region ../core/lib/dispatch.js
+/**
+* The default page for a model-facing `kb_list` — the SAME page the operator's `admin list` uses.
+*
+* Without one, `kb_list` on a large library read and parsed EVERY managed file (resolving a path
+* needs the file's frontmatter to detect collisions) to answer a question nobody asked in full. The
+* two surfaces were separate literals; the contract documents both as 50, so they are one constant
+* (`src/defaults.ts`).
+*/
+const KB_LIST_DEFAULT_LIMIT = 50;
 /** A document view with the managed file's path — what makes "edit it yourself" actionable. */
 function withFilePath(rt, doc) {
 	return {
@@ -3821,7 +3832,7 @@ const DISPATCH = {
 			const detail = rt.knowledge.detail(data.doc_id);
 			return detail === null ? { error: `文档不存在：doc_id=${String(data.doc_id)}` } : withFilePath(rt, detail);
 		}
-		return rt.knowledge.list(data.domain, data.source, data.limit ?? 50, data.offset).map((doc) => withFilePath(rt, doc));
+		return rt.knowledge.list(data.domain, data.source, data.limit ?? KB_LIST_DEFAULT_LIMIT, data.offset).map((doc) => withFilePath(rt, doc));
 	}),
 	kb_remove: ((rt, data) => rt.kb({
 		action: "remove",
@@ -7428,6 +7439,33 @@ function mergeFloorDrops(...parts) {
 function totalFloorDrops(drops) {
 	return drops.semantic + drops.fts + drops.jaccard + drops.hrr;
 }
+//#endregion
+//#region ../core/lib/store/hybrid.js
+/**
+* The retrieval orchestration BOTH stores run.
+*
+* `MemoryStore.search` and `KnowledgeStore.search` used to carry parallel copies of this flow
+* (~80 lines each: limit normalization → weights → over-fetch → leg cap → fuse → live filter →
+* slice → output budget → health event). The legs themselves are legitimately store-specific —
+* different tables, different filters (`category` vs `domain`/`source`), and only memory has the
+* HRR probe — but the ORCHESTRATION is one algorithm, and two copies of it drifted:
+*
+*   - the `NaN` limit guard existed only in memory, so a non-finite limit reached knowledge's SQL
+*     `LIMIT` and took the whole cross-store query down with it (`Promise.all` has no per-leg catch);
+*   - `retriever.over_fetch_factor` was read only by memory, while knowledge hardcoded `limit * 3`,
+*     so one config knob silently meant two different things;
+*   - `recordLegCapped()` was called only by memory, so a capped knowledge leg was unobservable —
+*     exactly the blindness DESIGN §20.17 says the counter exists to remove.
+*
+* Fixing those one at a time would leave the next drift a matter of when. The stores now supply
+* their legs and their hit mapping; everything that can drift lives here once.
+*
+* A leg that THROWS is isolated: it contributes nothing, the query still answers from the others,
+* and the failure is logged. The read path used to have no per-leg catch at all (the write path
+* did), so an ONNX error at inference cost the caller the FTS and entity legs too.
+*
+* @module store/hybrid
+*/
 /**
 * A retrieval input the CALLER got wrong, as opposed to a backend that failed at runtime.
 *
@@ -7488,7 +7526,7 @@ async function hybridSearch(deps, plan) {
 		fts: retriever.weight_fts,
 		jaccard: retriever.weight_jaccard
 	} : DEGRADED_WEIGHTS;
-	const overFetch = Math.max(limit, plan.overFetch ?? limit * (retriever.over_fetch_factor || 5));
+	const overFetch = Math.max(limit, plan.overFetch ?? limit * (retriever.over_fetch_factor || defaultConfig.retriever.over_fetch_factor));
 	const legCap = legCapFor(deps.config, overFetch);
 	const termCount = gradedTerms(query).length;
 	/**
@@ -8251,37 +8289,82 @@ async function forEachYielding(items, visit, every = 200) {
 		if ((index + 1) % every === 0) await yieldToEventLoop();
 	}
 }
+//#endregion
+//#region ../core/lib/store/vector_space.js
 /**
-* 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 ONE rule that decides whether a persisted vector can serve the store's CURRENT embedding
+* space — and therefore the one place the three counts (`stale` / `space_stale` / `legacy`) mean
+* anything.
 *
-* 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`).
+* The rule used to be written out five times (the shared open-time reload, the memory store's cheap
+* blob-length scan, the memory store's decode pass, the knowledge store's SQL projection and its
+* encode-source predicate), each in a slightly different shape: one over `Uint8Array`, one over a
+* projected `length(blob)`, one over a decoded `Float32Array`. They happened to agree; nothing made
+* them. A change to "what counts as stale" landing on one of them is exactly the silent two-spaces-
+* in-one-index failure `reportStaleVectors` exists to announce.
+*
+* The rule, as three elements (and nothing else):
+*
+*   1. `vec == null || byteLength !== dim * 4` → `stale` (the bytes cannot even decode into the
+*      current store);
+*   2. `embedding_model !== space` → `space_stale` (same width, another model's coordinates);
+*   3. of those, `isPreFingerprintSpace(...)` → `legacy` (a one-time format upgrade, not a model
+*      swap).
+*
+* WHAT IS NOT HERE: the SQL mirror (`ChunksDao.vectorSpaceCounts`) stays in SQL — it is what makes a
+* per-slice migration cheap (no blob is read) — and the cross assertions in
+* `test/vector_migration.spec.ts` / `test/knowledge_vector_migration.spec.ts` bind its counts to the
+* counts this module produces and to the startup warning. That is the direction the mirror has to be
+* checked in; a JS port of the SQL query would just be a sixth copy.
+*
+* @module store/vector_space
 */
-function loadVectorIndex(opts) {
-	reloadVectorIndex(opts.vstore, opts.rows, opts.store);
-	const expectedBytes = opts.vstore.dim * 4;
+/** How many bytes one element of a persisted vector BLOB costs (`float32ToBytes` writes LE f32). */
+const BYTES_PER_FLOAT32 = 4;
+/**
+* Classify ONE persisted vector. Pure: no store, no database, no logging — a caller that disagrees
+* with the result has to disagree with the rule, not with a copy of it.
+*
+* A caller-supplied vector is trusted to come from this backend, but its DIMENSION is still checked
+* — the same asymmetry `legs.ts` applies to a caller-supplied `queryVector`: provenance is the
+* caller's to assert, width is cheap and decides whether the bytes can be compared at all.
+*/
+function classifyVectorSpace(probe, identity) {
+	if (!(probe.source === "blob" ? probe.vec !== null && probe.vec !== void 0 && probe.vec.byteLength === identity.dim * BYTES_PER_FLOAT32 : probe.source === "byteLength" ? probe.byteLength === identity.dim * BYTES_PER_FLOAT32 : probe.vec !== null && probe.vec !== void 0 && probe.vec.length === identity.dim)) return {
+		verdict: "stale",
+		legacy: false
+	};
+	if (probe.embeddingModel !== identity.space) return {
+		verdict: "space_stale",
+		legacy: isPreFingerprintSpace(probe.embeddingModel)
+	};
+	return {
+		verdict: "current",
+		legacy: false
+	};
+}
+/**
+* {@link classifyVectorSpace} over a corpus: the `{ stale, space_stale, legacy }` triple the warning
+* and the `/mem` status surface report, counted by the same rule that classified each row.
+*
+* `legacy` counts only rows already counted in `space_stale` (`reportStaleVectors` clamps it there
+* too) — it is a REASON split, never a fourth bucket.
+*/
+function countVectorSpace(probes, identity) {
 	let stale = 0;
 	let spaceStale = 0;
 	let legacy = 0;
-	for (const row of opts.rows) {
-		if (row.vec === null || row.vec.byteLength !== expectedBytes) {
+	for (const probe of probes) {
+		const classified = classifyVectorSpace(probe, identity);
+		if (classified.verdict === "stale") {
 			stale++;
 			continue;
 		}
-		if (row.embedding_model !== opts.space) {
+		if (classified.verdict === "space_stale") {
 			spaceStale++;
-			if (isPreFingerprintSpace(row.embedding_model)) legacy++;
+			if (classified.legacy) legacy++;
 		}
 	}
-	reportStaleVectors(opts.store, opts.space, {
-		stale,
-		space_stale: spaceStale,
-		legacy
-	}, opts.manualEntry);
 	return {
 		stale,
 		space_stale: spaceStale,
@@ -8289,6 +8372,29 @@ function loadVectorIndex(opts) {
 	};
 }
 /**
+* 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 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 counts = countVectorSpace(opts.rows.map((row) => ({
+		source: "blob",
+		vec: row.vec,
+		embeddingModel: row.embedding_model
+	})), {
+		space: opts.space,
+		dim: opts.vstore.dim
+	});
+	reportStaleVectors(opts.store, opts.space, counts, opts.manualEntry);
+	return counts;
+}
+/**
 * 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
@@ -10479,22 +10585,53 @@ var FactsDao = class FactsDao {
 //#endregion
 //#region ../core/lib/db/dao/fact_sources.js
 /**
+* The closed `kind` vocabulary, spelled once so the store and the tests share it.
+*
+* The `satisfies` pins every member to the contract's union; the `Exclude` below pins the other
+* direction, so a kind the contract ADDS fails to compile here instead of silently never being
+* recorded.
+*/
+const FACT_SOURCE_KINDS = [
+	"session",
+	"kb_doc",
+	"tool",
+	"manual"
+];
+/**
+* The FALLBACK kind: a `source_ref` without a recognized `kind:` prefix is `manual` with the
+* reference kept VERBATIM (the tool contract says so, and "no shape guessing" is the point).
+*/
+const FACT_SOURCE_FALLBACK_KIND = "manual";
+/**
+* The kinds that act as a PREFIX — the vocabulary minus its own fallback, so a kind the contract adds
+* joins the prefix table by itself (via {@link FACT_SOURCE_KINDS}) and cannot be forgotten here.
+*/
+const FACT_SOURCE_PREFIX_KINDS = FACT_SOURCE_KINDS.filter((kind) => kind !== FACT_SOURCE_FALLBACK_KIND);
+/**
 * Derive `(kind, ref)` from the single `source_ref` the write face accepts.
 *
 * The tool takes ONE string (the plan adds no second parameter), so the kind axis is spelled by a
-* `kind:` prefix — `session:…` / `kb_doc:…` / `tool:…` — and anything else is `manual` with the
-* reference kept VERBATIM. No shape guessing: a bare `domain:source:title` becomes a `manual`
-* source whose ref is exactly what the caller wrote, which is strictly more honest than inventing
-* a category from how the string looks.
+* `kind:` prefix — `session:…` / `kb_doc:…` / `tool:…` — and anything else, INCLUDING the fallback
+* kind's own name, is `manual` with the reference kept VERBATIM. No shape guessing: a bare
+* `domain:source:title` becomes a `manual` source whose ref is exactly what the caller wrote, which
+* is strictly more honest than inventing a category from how the string looks.
+*
+* The prefix table comes from {@link FACT_SOURCE_KINDS} (see {@link FACT_SOURCE_PREFIX_KINDS}) rather
+* than from a hand-written alternation, which is what keeps the recognized set and the recorded set
+* from being two lists.
 */
 function classifySourceRef(sourceRef) {
-	const match = /^(session|kb_doc|tool):(.+)$/s.exec(sourceRef);
-	if (match !== null && match[2] !== void 0) return {
-		kind: match[1],
-		ref: match[2]
-	};
+	const separator = sourceRef.indexOf(":");
+	if (separator > 0) {
+		const prefix = sourceRef.slice(0, separator);
+		const ref = sourceRef.slice(separator + 1);
+		if (ref !== "" && FACT_SOURCE_PREFIX_KINDS.includes(prefix)) return {
+			kind: prefix,
+			ref
+		};
+	}
 	return {
-		kind: "manual",
+		kind: FACT_SOURCE_FALLBACK_KIND,
 		ref: sourceRef
 	};
 }
@@ -11551,26 +11688,14 @@ var MemoryStore = class {
 	* and every existing assertion on it — is unchanged; only the warning's wording uses it.
 	*/
 	vectorSpaceCounts() {
-		const space = this.vectorSpace();
-		const expectedBytes = this.vstore.dim * 4;
-		let stale = 0;
-		let spaceStale = 0;
-		let legacy = 0;
-		for (const row of this.facts.activeVectorSpaces()) {
-			if (row.bytes !== expectedBytes) {
-				stale++;
-				continue;
-			}
-			if (row.embedding_model !== space) {
-				spaceStale++;
-				if (isPreFingerprintSpace(row.embedding_model)) legacy++;
-			}
-		}
-		return {
-			stale,
-			space_stale: spaceStale,
-			legacy
-		};
+		return countVectorSpace(this.facts.activeVectorSpaces().map((row) => ({
+			source: "byteLength",
+			byteLength: row.bytes,
+			embeddingModel: row.embedding_model
+		})), {
+			space: this.vectorSpace(),
+			dim: this.vstore.dim
+		});
 	}
 	async add(content, category, ttlDays, opts) {
 		const normalized = normalizeWrite(content).trim();
@@ -12028,17 +12153,25 @@ var MemoryStore = class {
 		const counts = this.facts.vectorCounts();
 		const models = this.facts.embeddingModels();
 		const rows = this.facts.activeVectorRows();
-		const space = this.vectorSpace();
+		const identity = {
+			space: this.vectorSpace(),
+			dim: this.vstore.dim
+		};
 		const staleIds = [];
 		const spaceStaleIds = [];
 		const usable = [];
 		for (const r of rows) {
 			const vec = bytesToFloat32(r.semantic_vector);
-			if (!vec || vec.length !== this.vstore.dim) {
+			const classified = classifyVectorSpace({
+				source: "decoded",
+				vec,
+				embeddingModel: r.embedding_model
+			}, identity);
+			if (classified.verdict === "stale") {
 				staleIds.push(r.fact_id);
 				continue;
 			}
-			if (r.embedding_model !== space) spaceStaleIds.push(r.fact_id);
+			if (classified.verdict === "space_stale") spaceStaleIds.push(r.fact_id);
 			usable.push({
 				id: r.fact_id,
 				vec
@@ -13069,6 +13202,12 @@ var ChunksDao = class {
 	* 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).
+	*
+	* The JS rule itself is `store/vector_space.ts` (`classifyVectorSpace` / `countVectorSpace`), and
+	* this projection is bound to it by the cross assertions in
+	* `test/knowledge_vector_migration.spec.ts` (the startup warning's count, the health count and the
+	* migration's `remaining` all have to be the same number). NOTHING here changes when the JS rule
+	* changes: the mirror is checked, not shared.
 	*/
 	vectorSpaceCounts(space, expectedBytes) {
 		const row = this.db.prepare(`SELECT
@@ -18472,7 +18611,7 @@ async function apply(ctx, config) {
 	logger.info(wellFormed.text && wellFormed.deep ? "well-formed repair: the base kit's wellFormedText/wellFormedDeep (interface v2)" : "well-formed repair: the mem mirror (the base is absent, or predates the v2 helpers)");
 	const compat = env?.compat;
 	let verdict;
-	if (compat === void 0) logger.warn("plugin mount: the dsh compatibility gate is ABSENT (@avantf/dsh-plugin-base unavailable — see the WARNING above); mounting the full plugin anyway");
+	if (compat === void 0) logger.warn("plugin mount: the dsh compatibility gate is UNAVAILABLE (@avantf/dsh-plugin-base is absent, or it is another interface generation — see the WARNING above); mounting the full plugin anyway");
 	else {
 		const run = provision(ctx, logger, compat);
 		if (!run.verdict.load) {
@@ -18634,7 +18773,8 @@ async function apply(ctx, config) {
 	new AvantfMemGateway(ctx, rt);
 	logger.info("remote registered: avantfMem (client ctx.remote.avantfMem.*)");
 	const disposeTypert = ctx.typert.register(hostContribution);
-	logger.info("typert registered: avantfMem host face (5 tools + 5 UI-only)");
+	const toolBackedMethods = descriptors.filter((descriptor) => toolSpecs.some((spec) => spec.key === descriptor.method)).length;
+	logger.info(`typert registered: avantfMem host face (${String(toolBackedMethods)} tool-backed + ${String(descriptors.length - toolBackedMethods)} UI-only Remote methods)`);
 	if (compat !== void 0) verifyRegisteredFaces({
 		ctx,
 		toolNames: toolSpecs.map((spec) => spec.name),

package/lib/interface-version.json

@@ -1,4 +1,4 @@
 {
-  "baseVersion": "0.4.2",
-  "interfaceVersion": 3
+  "baseVersion": "0.5.2",
+  "interfaceVersion": 4
 }

package/lib/types/envinit-bootstrap.d.ts

@@ -3,18 +3,20 @@
  * @module bootstrap
  */
 /** The bootstrap version; the resolved framework must satisfy {@link supportedRange}. */
-export declare const VERSION = "0.4.2";
+export declare const VERSION = "0.5.2";
 /**
  * The framework interval this bootstrap can launch.
  *
- * Kept equal to the plugins' peer range for the base: the plugin passes no override, so THIS is the
- * runtime gate. It is a plain comparator interval, NOT a caret: the package version is ordinary
- * semver again and no longer tracks the interface, so the interval stays as wide as the family's
- * compatibility promise — `>=0.3.0 <1.0.0` admits every 0.x base this generation of plugins can
- * consume, and stops at the major that invented a new interface generation. The interface itself is
- * the separate, runtime axis: a base inside this interval whose `INTERFACE_VERSION` differs is judged
- * by the base's own gate (INTERFACE.md §1, §3) — an OLDER base degrades, a NEWER one is `ok` + a
- * warning (generations are additive), and neither ever refuses the mount.
+ * This is the PACKAGE-version window, and nothing else: the interval is byte-for-byte the range the
+ * plugins declare in their `dependencies` for the base (the install-time gate; the base is a plain
+ * dependency, not a peer) and the plugin passes no override, so THIS is the runtime gate too. It is
+ * a plain comparator interval, NOT a caret: the package version is ordinary semver and does not
+ * track the interface, so the interval stays as wide as the family's compatibility promise —
+ * `>=0.3.0 <1.0.0` admits every 0.x base this generation of plugins can consume. Its upper bound
+ * marks no generation boundary. Generation is the separate, runtime axis, judged on its own: the
+ * base's `INTERFACE_VERSION` is compared by the base's gate (INTERFACE.md §1, §3) — an OLDER base
+ * degrades to `incompatible`, a NEWER one is `ok` + a WARNING (generations are additive), and
+ * neither ever refuses the mount.
  */
 export declare const supportedRange = ">=0.3.0 <1.0.0";
 /** Sink for the warnings that replace a throw. */

package/lib/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AASlD,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAExC,OAAO,EAAE,mBAAmB,EAAU,MAAM,kCAAkC,CAAA;AAE9E,OAAO,EASL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,WAAW,EAEhB,KAAK,WAAW,EACjB,MAAM,aAAa,CAAA;AACpB,OAAO,EAaL,KAAK,aAAa,EAClB,KAAK,WAAW,EAEhB,KAAK,YAAY,EACjB,KAAK,cAAc,EAEnB,KAAK,oBAAoB,EAG1B,MAAM,sBAAsB,CAAA;AAqB7B,eAAO,MAAM,IAAI,eAAe,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAGpC,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAQ7E,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,WAAW,GACjB,MAAM,aAAa,CAAA;AAEpB,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAA;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AACD,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAO3B,CAAA;AAkCF,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAOvC;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,SAAQ,mBAAmB;IACvD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAe;gBACtB,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,aAAa;IAK3C;;;;;;;;;OASG;YACW,IAAI;IAclB;;;;OAIG;IAEH,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC;IAMlF,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IAMnF,KAAK,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;IAKhF;;;;;OAKG;IAEH,EAAE,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAOpD,KAAK,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAI5D;;;;OAIG;IAEG,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,oBAAoB,CAAC,CAAC;IAUnF,qFAAqF;IAE/E,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IAUvE;;;;OAIG;IAEG,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC,CAAC;IAQvG;;;;OAIG;IAEG,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC;IAUpG;;;;;OAKG;IAEG,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;CAiBpE;AAmHD,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyYvE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AASlD,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAExC,OAAO,EAAE,mBAAmB,EAAU,MAAM,kCAAkC,CAAA;AAE9E,OAAO,EASL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,WAAW,EAEhB,KAAK,WAAW,EACjB,MAAM,aAAa,CAAA;AACpB,OAAO,EAaL,KAAK,aAAa,EAClB,KAAK,WAAW,EAEhB,KAAK,YAAY,EACjB,KAAK,cAAc,EAEnB,KAAK,oBAAoB,EAG1B,MAAM,sBAAsB,CAAA;AAqB7B,eAAO,MAAM,IAAI,eAAe,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAGpC,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAQ7E,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,WAAW,GACjB,MAAM,aAAa,CAAA;AAEpB,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAA;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AACD,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAO3B,CAAA;AAkCF,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAOvC;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,SAAQ,mBAAmB;IACvD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAe;gBACtB,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,aAAa;IAK3C;;;;;;;;;OASG;YACW,IAAI;IAclB;;;;OAIG;IAEH,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC;IAMlF,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IAMnF,KAAK,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;IAKhF;;;;;OAKG;IAEH,EAAE,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAOpD,KAAK,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAI5D;;;;OAIG;IAEG,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,oBAAoB,CAAC,CAAC;IAUnF,qFAAqF;IAE/E,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IAUvE;;;;OAIG;IAEG,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC,CAAC;IAQvG;;;;OAIG;IAEG,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC;IAUpG;;;;;OAKG;IAEG,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;CAiBpE;AAmHD,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyZvE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avantf/dsh-mem",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "avantf-mem DSH native Cordis plugin: host service + tools + RPC + client tabs 记忆/知识",
   "type": "module",
   "main": "lib/index.js",
@@ -78,10 +78,10 @@
   },
   "devDependencies": {
     "@avantf/dsh-plugin-base": ">=0.3.0 <1.0.0",
-    "@avantf/mem": "0.6.3",
-    "@avantf/mem-contract": "0.6.3",
-    "@avantf/mem-convert": "0.6.3",
-    "@avantf/mem-provision": "0.6.3",
+    "@avantf/mem": "0.6.4",
+    "@avantf/mem-contract": "0.6.4",
+    "@avantf/mem-convert": "0.6.4",
+    "@avantf/mem-provision": "0.6.4",
     "@types/node": "^22.0.0",
     "@types/react": "^18.3.0",
     "lightningcss": "^1.32.0",