@avantf/dsh-mem 0.3.1 → 0.4.0

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

@@ -0,0 +1,207 @@
+import type { AvantfRuntime } from './runtime.js';
+/** The statuses the base's verdict can carry (kept structural — see the note above). */
+export type DshCompatStatus = 'ok' | 'version-mismatch' | 'version-unknown' | 'probe-skipped' | 'probe-failed';
+/**
+ * The slice of the base's verdict this package reads.
+ *
+ * `load: false` means a probe PROVED the host API incompatible (only `probe-failed`); a version
+ * difference is a warning, never a skip. Structural on purpose: a full `CompatVerdict` from the base
+ * satisfies it, and this package needs no import of (or dependency on) the base to say so.
+ */
+export interface DshCompatVerdict {
+    readonly load: boolean;
+    readonly status: DshCompatStatus;
+    readonly reason: string;
+}
+/** Options for {@link warmModels}. */
+export interface WarmOptions {
+    /**
+     * Resolve before the tokenizer parse starts. The DSH plugin passes its host's readiness signal
+     * (`loader.await()`), the same one that gates the `dsh web` URL line, so the synchronous parse
+     * runs once the host is up instead of delaying it.
+     */
+    waitFor?: Promise<unknown>;
+    /**
+     * Hard cap on {@link waitFor} (default {@link WAIT_FOR_HOST_MS}).
+     *
+     * The host's own readiness signal is not bounded by the host (its URL print relies on the same
+     * promise), so a loader row that never settles would leave the tokenizer un-warmed for the whole
+     * process life — every first query then pays the ~1.2 s. Bounded here on principle, and
+     * injectable so a caller can shorten it without waiting the real interval.
+     */
+    waitForCapMs?: number;
+    /**
+     * Wait for an idle event loop before loading nodejieba (the host-boot path). Off for the CLI,
+     * which calls `warmModels` inline: there the process is already idle and the gate would only add
+     * its quiet window to every command. The name is tokenizer-shaped for history, but the gate is the
+     * general "do not run synchronous startup mission during the boot burst" one — the plugin's
+     * mount-time entity sweep passes the same flag through {@link awaitStartupGate}.
+     */
+    deferTokenizerUntilIdle?: boolean;
+}
+/**
+ * Fire-and-forget model bootstrap for DSH startup. Configures the semantic /
+ * rerank model env (mirror + cache) and triggers the model download/load
+ * asynchronously, without blocking the plugin's `apply`. Returns the availability
+ * of the semantic path once the download/load completes.
+ *
+ * Every stage logs through the runtime logger so a plugin mount is traceable in
+ * the DSH host output: warm start (mirror/cache/model), then ready or degraded.
+ *
+ * @param rt - the runtime whose memory store owns the semantic backend.
+ * @param options - host-readiness and idle-gating options (see {@link WarmOptions}).
+ * @param reportFinal - log the one-line verdict (`true`, the default). The provisioning sweep turns
+ *   the same verdict into the artifact's result line and would otherwise print it twice; the CLI
+ *   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.
+ *
+ * Extracted so there is exactly ONE definition of "a job that must not run inside the host's boot
+ * window". The tokenizer warm below uses it, and so does the plugin's mount-time entity sweep:
+ * `reindexEntities` tags stale rows through nodejieba, whose dictionary parse is the same ~1.2 s
+ * SYNCHRONOUS mission the warm defers, so a sweep fired at mount (before this) could pull that parse
+ * back into the startup window through a second door (performance review §7.5 / P5).
+ *
+ * The waits are NOT preconditions: a host whose boot failed still resolves them, and a host whose
+ * boot hung is bounded here rather than trusted (see {@link WarmOptions.waitForCapMs}).
+ *
+ * @param options - the same options the tokenizer warm takes (the idle gate is opt-in).
+ * @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.
+ *
+ * The plugin's envinit path calls this from the model item's `onSettled`, which is the "continue
+ * initialisation once the background resource is there" step (framework DESIGN §7.2 step 5).
+ *
+ * @param rt - the runtime to warm.
+ * @param reportFinal - log the one-line verdict (default `true`).
+ */
+export declare function warmSemanticAsync(rt: AvantfRuntime, reportFinal?: boolean): void;
+/**
+ * Non-blocking tokenizer warm for the plugin startup path: the host is still mounting plugins and
+ * composing its client bundles, so the synchronous dictionary parse waits for the host's readiness
+ * signal (when one is available) and then for a quiet turn, instead of competing with the boot.
+ *
+ * @param rt - the runtime to warm.
+ * @param options - the host-readiness signal and the idle gate (see {@link WarmOptions}).
+ */
+export declare function warmTokenizerAsync(rt: AvantfRuntime, options?: WarmOptions): void;
+/**
+ * Options for {@link provisionToolchainAsync}: the warm-up options plus the host-side dsh verdict.
+ */
+export interface ProvisionSweepOptions extends WarmOptions {
+    /**
+     * The verdict the DSH plugin ALREADY computed (see `packages/plugin/src/provision.ts`), as plain
+     * data. The plugin computes it once and this package reads it — no second derivation, and no
+     * import of the base. Absent for callers with no dsh context (the standalone MCP entry), in which
+     * case no gate runs.
+     */
+    dshCompat?: DshCompatVerdict;
+}
+/** Outcome of {@link provisionToolchainAsync}. */
+export interface ProvisionSweepResult {
+    /**
+     * `true` when the sweep did NOT run because the host dsh is incompatible: no artifact was
+     * resolved, installed or warmed. `false` means the sweep was dispatched as usual.
+     */
+    skipped: boolean;
+    /** Verdict status when the gate ran (`probe-failed` is the only value that skips). */
+    status?: DshCompatStatus;
+    /** Why it was skipped (the proven incompatibility detail). */
+    reason?: string;
+}
+/**
+ * The ONE startup initialization for this plugin: register every artifact this build needs, then run
+ * the provisioning sweep (non-blocking).
+ *
+ * It replaced a one-shot model warm-up that sat beside a separate tools sweep, which meant two
+ * initialization paths, two logging vocabularies, and no single answer to "is this host fully
+ * provisioned?". Callers (the DSH plugin mount, the MCP entry) now make one call, and the per-artifact
+ * result lines in the host log come from the same mechanism that installs pandoc.
+ *
+ * The FIRST step is the dsh compatibility gate: an incompatible host means NOTHING is resolved,
+ * installed or warmed — preparing an environment for an API we cannot drive is wasted mission.
+ *
+ * @param rt - the runtime, whose resolved `tools` config and logger the sweep uses.
+ * @param options - the host's readiness signal and the dsh compatibility evidence.
+ * @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/router.d.ts

@@ -0,0 +1,51 @@
+import { type RecallHit, type RecallResult, type RetrievalFloorDrops } from '../mem-contract/index.js';
+interface CrossQueryOptions {
+    limit?: number;
+    kind?: 'all' | 'fact' | 'doc_chunk';
+    domain?: string;
+    source?: string;
+    /**
+     * Token budget for the merged result; `0` = unlimited, omitted = the caller already bounded
+     * the legs (the runtime lifts the per-store budgets for the pool and bounds the OUTCOME here,
+     * because fusion can reorder which entries deserve the text).
+     */
+    maxTokens?: number;
+    /**
+     * The knowledge leg's floor report. `KnowledgeStore.search` answers with hits only, so the
+     * runtime hands its captured `HybridResult` drops here; the memory side already arrives on
+     * `memory.dropped_by_floor`. Without this, the merged result would report only half the floors.
+     */
+    kbDroppedByFloor?: RetrievalFloorDrops;
+}
+/** The memory search result the router derives degradation/weights from. */
+type CrossQueryMemory = Pick<RecallResult, 'hits' | 'degraded' | 'weights' | 'floors' | 'dropped_by_floor'>;
+/**
+ * Joint min-max normalization over the MERGED pool — the rule the cross-store score
+ * contract is defined by (DESIGN §7).
+ *
+ * Degenerate case (every candidate carries the same score — including a pool of one):
+ * the raw score is KEPT. A collapsed range encodes no ranking information, so rescaling
+ * it would invent a "perfect match" out of an absolute fused score that may say
+ * otherwise. `minMaxNormalize` maps the same case to 1 instead, which is right there
+ * because it only ever feeds a relative weighted sum inside ONE fusion path; the two
+ * differ deliberately rather than by oversight.
+ *
+ * Returns COPIES: the inputs are the stores' own result objects, and callers still
+ * read their original scores.
+ */
+export declare function normalizeMergedScores<T extends {
+    score: number;
+}>(pool: T[]): T[];
+/**
+ * Cross-retrieval router: merge memory + knowledge hits, joint min-max normalize
+ * the final fused scores over the *combined* pool (so the two stores' scores are
+ * comparable), then rank by score.
+ *
+ * Degradation and weights are inherited from the memory search result rather
+ * than hardcoded: both stores share the same semantic adapter, so
+ * `memory.degraded`/`memory.weights` already describe whether the semantic leg
+ * ran. Reporting a fixed `degraded: true` here made every `kb_query` look
+ * degraded even when embeddings were live.
+ */
+export declare function crossQuery(memory: CrossQueryMemory, kb: RecallHit[], opts?: CrossQueryOptions): RecallResult;
+export {};

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

@@ -0,0 +1,232 @@
+import type { AdminRequest, KbAddRequest, KbConflictReport, KbRequest, QueryRequest, RecallRequest, RecallResult, RememberRequest } from '../mem-contract/index.js';
+import { type AvantfLogger, type StatsSummary } from '../mem-contract/index.js';
+import { type SemanticBackend } from '../mem-retrieval/index.js';
+import { type LoadedConfig } from './config/loader.js';
+import { type Db } from './db/conn.js';
+import { type RelevanceHit } from './store/lexical.js';
+import { MemoryStore } from './store/memory.js';
+import { KnowledgeStore } from './store/knowledge.js';
+export interface RuntimeOptions {
+    dataHome?: string;
+    memoryDbPath?: string;
+    /** Host logger; defaults to the prefixed console logger. */
+    logger?: AvantfLogger;
+    /**
+     * Override the semantic backend instead of resolving `semantic.backend` through the
+     * registry. A seam for tests and embedders, NOT a second pluggability path: the registry
+     * + config stays the documented way to swap backends (DESIGN §5). The override must
+     * produce vectors of `config.semantic.dim`, since the vector stores are built from it.
+     */
+    semantic?: SemanticBackend;
+    /**
+     * The family framework's managed roots, as the built-in defaults for `tools.dir` and
+     * `semantic.cache_dir` / `rerank.cache_dir` (see `LoadConfigOptions.managedRoots`).
+     *
+     * The DSH plugin passes `<family home>/tools` and `<family home>/models` while
+     * `@avantf/dsh-plugin-base` owns the fetching; the CLI and the MCP server pass nothing, because they
+     * provision through `@avantf/mem-provision` as before.
+     *
+     * This also decides WHEN the local models warm: with managed roots the framework may still be
+     * writing the model into that root, so the backends are resolved with `deferWarm` and the plugin
+     * warms them once the framework's item settles. Without managed roots the adapters keep their
+     * eager constructor warm.
+     */
+    managedRoots?: {
+        readonly tools?: string;
+        readonly models?: string;
+    };
+}
+/**
+ * The awaited result of a store method — what a dispatch overload promises.
+ *
+ * Every member below is written in terms of the METHOD that produces it rather than a type
+ * spelled out by hand. That is the whole point: an invented type (`Promise<RecallResult>` for
+ * `related`, which answers with entity counts) compiles perfectly and then lies to every caller,
+ * while `ReturnType<Store['method']>` cannot disagree with the store. The trailing general
+ * overloads keep dynamic dispatchers (the plugin's tool runner, MCP) compiling, where the request
+ * arrives as the whole union.
+ *
+ * Exported because the DSH plugin's Remote gateway is a dynamic dispatcher too, and it should be able
+ * to say what each key answers without inventing a shape: `StoreResult<MemoryStore, 'add'>` is the
+ * fact the store actually wrote, whatever the store's author later changes it to.
+ */
+export type StoreResult<S, M extends keyof S> = Awaited<ReturnType<Extract<S[M], (...args: never[]) => unknown>>>;
+/**
+ * A caller-error payload — the shape every self-made refusal in the `switch` returns.
+ *
+ * Named so the return sites can assert it (`satisfies DispatchError`): these payloads are the
+ * only ones NOT produced by a store method, so they have no `ReturnType` to be tied to.
+ */
+export type DispatchError = {
+    error: string;
+};
+/**
+ * `admin.stats`: the store counts plus the process-wide retrieval health block (DESIGN §20) — the one
+ * admin payload no store method produces, because the runtime composes it.
+ */
+export type AdminStatsResult = StatsSummary;
+/**
+ * The payload of the four hits-returning recall actions, which one overload groups because a
+ * caller may hold them as a union (`action: 'chain' | 'reason'`).
+ *
+ * Grouping them is a CLAIM — that `probe`, `chain` and `reason` all answer like `search` — so it is
+ * proven rather than assumed: a type-level check asserts that each store method's result equals this
+ * one, and a divergence fails there instead of the grouped overload quietly lying about it. (Only
+ * `probe` holds by construction, because it calls `memory.search`.)
+ */
+export type RecallHitsResult = StoreResult<MemoryStore, 'search'>;
+/**
+ * `remember` dispatches to five store operations whose RESULTS differ: `add`/`update` return the
+ * written fact, `remove` a flag, the feedback actions the new counter (or `null`). One plain
+ * signature would either say `unknown` — leaving every caller to invent a cast, which is how a
+ * caller ends up reading a field that does not exist — or a union that forces every caller to
+ * narrow first. The callable type says what each ACTION returns.
+ */
+export type RememberDispatch = {
+    (req: Extract<RememberRequest, {
+        action: 'add';
+    }>): Promise<StoreResult<MemoryStore, 'add'>>;
+    (req: Extract<RememberRequest, {
+        action: 'update';
+    }>): Promise<StoreResult<MemoryStore, 'update'>>;
+    (req: Extract<RememberRequest, {
+        action: 'remove';
+    }>): Promise<StoreResult<MemoryStore, 'remove'>>;
+    (req: Extract<RememberRequest, {
+        action: 'helpful' | 'unhelpful';
+    }>): Promise<StoreResult<MemoryStore, 'helpful'>>;
+    (req: RememberRequest): Promise<unknown>;
+};
+/**
+ * Same per-action idea as {@link RememberDispatch}. `ask` may also report a caller error, and
+ * `related` answers with ENTITY COUNTS rather than hits (`memory.related`) — a distinction that
+ * only showed up once this type existed, because the callers had been casting to whatever they
+ * assumed.
+ */
+export type RecallDispatch = {
+    (req: Extract<RecallRequest, {
+        action: 'search' | 'probe' | 'chain' | 'reason';
+    }>): Promise<RecallHitsResult>;
+    (req: Extract<RecallRequest, {
+        action: 'ask';
+    }>): Promise<StoreResult<MemoryStore, 'ask'> | DispatchError>;
+    (req: Extract<RecallRequest, {
+        action: 'related';
+    }>): Promise<StoreResult<MemoryStore, 'related'>>;
+    (req: Extract<RecallRequest, {
+        action: 'contradict';
+    }>): Promise<StoreResult<MemoryStore, 'listContradictions'>>;
+    (req: RecallRequest): Promise<unknown>;
+};
+/**
+ * `admin` is the widest dispatcher: counts, a fact page, a detail, flags, and five diagnostic
+ * reports. `ReturnType<…>` keeps each member tied to the store method that actually produces it,
+ * so a change there propagates instead of leaving callers with a cast they invented.
+ */
+export type AdminDispatch = {
+    (req: Extract<AdminRequest, {
+        action: 'stats';
+    }>): AdminStatsResult;
+    (req: Extract<AdminRequest, {
+        action: 'list';
+    }>): StoreResult<MemoryStore, 'list'>;
+    (req: Extract<AdminRequest, {
+        action: 'detail';
+    }>): StoreResult<MemoryStore, 'get'> | DispatchError;
+    (req: Extract<AdminRequest, {
+        action: 'archive';
+    }>): StoreResult<MemoryStore, 'archive'>;
+    (req: Extract<AdminRequest, {
+        action: 'restore';
+    }>): StoreResult<MemoryStore, 'restore'>;
+    (req: Extract<AdminRequest, {
+        action: 'pin';
+    }>): StoreResult<MemoryStore, 'pin'>;
+    (req: Extract<AdminRequest, {
+        action: 'unpin';
+    }>): StoreResult<MemoryStore, 'unpin'>;
+    (req: Extract<AdminRequest, {
+        action: 'trust_diagnose';
+    }>): StoreResult<MemoryStore, 'trustDiagnose'>;
+    (req: Extract<AdminRequest, {
+        action: 'vectors_diagnose';
+    }>): StoreResult<MemoryStore, 'vectorsDiagnose'>;
+    (req: Extract<AdminRequest, {
+        action: 'vectors_fix';
+    }>): StoreResult<MemoryStore, 'vectorsFix'>;
+    (req: Extract<AdminRequest, {
+        action: 'contradict_check';
+    }>): StoreResult<MemoryStore, 'checkContradictions'>;
+    (req: Extract<AdminRequest, {
+        action: 'contradict_resolve';
+    }>): StoreResult<MemoryStore, 'resolveContradiction'>;
+    (req: Extract<AdminRequest, {
+        action: 'maintenance';
+    }>): StoreResult<MemoryStore, 'maintenance'>;
+    (req: AdminRequest): unknown;
+};
+/**
+ * `kb_manage`: ingest/import report a batch, list/detail the corpus, remove a flag, reindex a
+ * plan. Members are pinned to the store methods that produce them (`ReturnType<…>`) so the
+ * shapes cannot drift into "whatever the caller assumed".
+ *
+ * `ingest`/`import` may instead answer with a {@link KbConflictReport}: this face is the UI/CLI
+ * REPLACE mode, where an unconfirmed collision writes nothing and comes back as a structured
+ * list. The add-only face (`kbAdd`) never returns one — it refuses.
+ */
+export type KbDispatch = {
+    (req: Extract<KbRequest, {
+        action: 'ingest';
+    }>): Promise<StoreResult<KnowledgeStore, 'ingest'> | KbConflictReport | DispatchError>;
+    (req: Extract<KbRequest, {
+        action: 'import';
+    }>): Promise<StoreResult<KnowledgeStore, 'importPaths'> | KbConflictReport>;
+    (req: Extract<KbRequest, {
+        action: 'list';
+    }>): Promise<StoreResult<KnowledgeStore, 'list'>>;
+    (req: Extract<KbRequest, {
+        action: 'detail';
+    }>): Promise<StoreResult<KnowledgeStore, 'detail'>>;
+    (req: Extract<KbRequest, {
+        action: 'remove';
+    }>): Promise<StoreResult<KnowledgeStore, 'remove'>>;
+    (req: Extract<KbRequest, {
+        action: 'reindex';
+    }>): Promise<StoreResult<KnowledgeStore, 'reindex'>>;
+    (req: KbRequest): Promise<unknown>;
+};
+export interface AvantfRuntime {
+    config: LoadedConfig;
+    db: Db;
+    memory: MemoryStore;
+    knowledge: KnowledgeStore;
+    /** Logger every startup/lifecycle line goes through. */
+    logger: AvantfLogger;
+    remember: RememberDispatch;
+    recall: RecallDispatch;
+    admin: AdminDispatch;
+    kb: KbDispatch;
+    /**
+     * The ADD-ONLY face of the same shared ingestion entry (`kb_add`): same plan/classify/dispatch,
+     * but a collision is refused instead of replaced. Kept as its own runtime method — not a field on
+     * the request — so the model-facing `KB_ADD_TOOL.input` cannot even express "replace".
+     */
+    kbAdd(req: KbAddRequest): Promise<unknown>;
+    query(req: QueryRequest): Promise<RecallResult>;
+    /**
+     * Plugin-internal, NOT a tool and not model-facing: does either store already hold something
+     * relevant to `text`? A boolean (`store/lexical.ts`) because the one tool the hint names
+     * (`kb_query`) retrieves from both stores, so "which one matched" changes no downstream decision.
+     * Synchronous on purpose — the caller renders it into a prompt provider that cannot await
+     * (DESIGN §12).
+     */
+    relevance(text: string): RelevanceHit;
+    /**
+     * True once {@link shutdown} has run: the databases are closed and no background pass may start.
+     * A gated startup job checks this (as well as the plugin's fiber) before touching the stores.
+     */
+    readonly closed: boolean;
+    shutdown(): void;
+}
+/** Build the runtime: load config, open the memory DB, construct the stores. */
+export declare function buildRuntime(opts?: RuntimeOptions): AvantfRuntime;

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

@@ -0,0 +1,82 @@
+/**
+ * Pieces both stores need identically.
+ *
+ * Small on purpose: `MemoryStore` and `KnowledgeStore` are separate stores over separate databases
+ * and should stay that way (AGENTS.md). What they must NOT have is two copies of the same
+ * three-line helper, because a fix then lands in one of them — which is exactly what happened to the
+ * retrieval orchestration (see `store/hybrid.ts`) and to the foreign-vector-space warning below: the
+ * memory store checked whether its persisted vectors came from the CURRENT vector space and told the
+ * operator how to fix it, while the knowledge store checked only the width, so a model swap left two
+ * spaces silently mixed in one index until someone happened to run `kb_reindex`.
+ *
+ * @module store/common
+ */
+import type { SemanticBackend, VectorStore } from '../../mem-retrieval/index.js';
+/**
+ * The ONE write-side normalization both stores call before anything reaches the database.
+ *
+ * `@avantf/mem-contract`'s `toWellFormedText` is the implementation (well-formed + NFC); this name
+ * is the store-layer entry, so the write paths say WHAT they are doing ("normalize this for a
+ * write") rather than repeating a Unicode recipe. Every text field a store persists — fact content,
+ * category, archive reason, a document's domain/source/title/uri, entity names and the SPO slots of
+ * extracted triples — goes through here, which is what keeps a lone surrogate (and the strict-JSON
+ * failure it causes downstream) out of the database in the first place.
+ */
+export declare function normalizeWrite(value: string): string;
+/** {@link normalizeWrite} over a batch (entity names, caller paths, …). */
+export declare function normalizeWrites(values: readonly string[]): string[];
+/**
+ * Identity of the vector space a store currently writes into.
+ *
+ * A change of backend, model or width makes every stored vector stale, and the point of recording
+ * the identity is that such a change is DETECTED instead of silently mixing two spaces in one index.
+ */
+export declare function vectorSpaceOf(semantic: SemanticBackend, model: string): string;
+/**
+ * Drop ids from the vector index, in one batch when the backend supports it.
+ *
+ * `removeMany` is optional on the interface: a backend that cannot delete incrementally would make
+ * an eviction loop O(N²) without it, and hnswlib's is O(k) tombstoning.
+ */
+export declare function evictVectors(vstore: VectorStore, ids: readonly number[]): void;
+/**
+ * Tell the operator that persisted vectors came from ANOTHER vector space.
+ *
+ * A dim-valid vector from a different space is still RANKED — the reload cannot tell the difference
+ * — so a silent model swap would mix two spaces in one index and degrade every semantic query
+ * without an error anywhere. Said once per process; acting on it is the operator's choice because
+ * re-encoding is a real cost (and they should see the count first).
+ *
+ * @param kind   store label for the message (`memory` / `knowledge`)
+ * @param space  the vector space the store writes into now
+ * @param foreign how many persisted vectors were written in a different one
+ * @param fix    the action that re-encodes them, as the operator would type it
+ */
+export declare function reportForeignVectors(kind: string, space: string, foreign: number, fix: string): void;
+/**
+ * Hand the event loop back between two synchronous batches.
+ *
+ * The mount-time corpus reconcile reads and hashes EVERY managed document (and then walks the tree
+ * again for orphans), all of it synchronous `node:fs`; at 10k documents that is a >0.6 s block of the
+ * host's event loop (measured — see the performance review §7.5 / P6). `setImmediate` (a macrotask),
+ * not a resolved-promise microtask: yielding to the microtask queue would let other JS continuations
+ * run while timers and I/O queued behind the batch still waited.
+ */
+export declare function yieldToEventLoop(): Promise<void>;
+/**
+ * How many items one synchronous batch may visit before {@link yieldToEventLoop} runs.
+ *
+ * 200 is a compromise: large enough that the yields themselves are noise next to the per-item
+ * `read`+`sha256` (measured ~60 µs each), small enough that the longest single block stays in the
+ * low tens of milliseconds at any corpus size.
+ */
+export declare const YIELD_BATCH = 200;
+/**
+ * Visit `items` in order, yielding the event loop every `every` items.
+ *
+ * Use this INSTEAD of a bare `for` loop whenever the per-item mission is synchronous filesystem or
+ * hashing work whose item count follows the corpus (not the request): the caller's whole loop used to
+ * be one uninterrupted block, so the host could not serve a timer or an I/O callback until it was
+ * over. An empty list does nothing (and never yields).
+ */
+export declare function forEachYielding<T>(items: readonly T[], visit: (item: T, index: number) => void, every?: number): Promise<void>;