@avantf/dsh-mem 0.6.4 → 0.8.0

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

@@ -1,5 +1,5 @@
 /**
- * The ONE vector-space repair flow both stores run.
+ * The vector-space repair flow the memory store runs.
  *
  * Changing the embedding space (model, width, pooling, normalization, input window, weights) is a
  * DATA MIGRATION: persisted vectors keep decoding but live in another model's coordinates, so the
@@ -8,26 +8,25 @@
  * slices and yields the event loop between them.
  *
  * It is a template method implemented by COMPOSITION (AGENTS.md / the design note in
- * `docs/vector-repair-shared-flow.md`): the skeleton lives here as free functions, each store
- * supplies a {@link VectorRepairTarget} adapter. No common base class — the two stores are separate
- * databases with separate DAOs, and a base class would be a structural rewrite of two hub files.
+ * `docs/vector-repair-shared-flow.md`): the skeleton lives here as free functions, and the store
+ * supplies a {@link VectorRepairTarget} adapter. No base class.
  *
- * What is shared, and therefore must never be copied back into `store/memory.ts` /
- * `store/knowledge.ts`: the batch size, the `yieldToEventLoop` call, the stop / resume / no-progress
- * rules, the `semantic.auto_migrate` decision, the `dry_run` split, the order invariant
- * (unusable bytes leave first, then re-encode), the warmup policy and the four log kinds.
+ * What is shared, and therefore must never be copied back into `store/memory.ts`: the batch size,
+ * the `yieldToEventLoop` call, the stop / resume / no-progress rules, the `semantic.auto_migrate`
+ * decision, the `dry_run` split, the order invariant (unusable bytes leave first, then re-encode),
+ * the warmup policy and the four log kinds.
  *
- * What stays in the stores (correct differences, DESIGN §2.3): the DAO calls and row shapes, the
- * `conflict_checked` re-queue on the memory side, the `content_hash` reuse and failure counting on
- * the knowledge side, the HRR column, and which live index a row is added to.
+ * What stays in the store (DESIGN §2.3): the DAO calls and row shapes, the `conflict_checked`
+ * re-queue, the HRR column, and which live index a row is added to.
  *
  * @module store/vector_repair
  */
 import type { AvantfLogger, VectorMigrationOutcome, VectorMigrationProgress, VectorsFixReport, VectorsFixStoreReport } from '../../mem-contract/index.js';
 import type { VectorStore } from '../../mem-retrieval/index.js';
+import type { Awaitable } from '../interfaces/common.js';
 import { type StaleVectorCounts } from './common.js';
-/** The two stores this flow can drive. */
-export type VectorRepairStore = 'memory' | 'knowledge';
+/** The store this flow drives. */
+export type VectorRepairStore = 'memory';
 /**
  * Rows one background vector-space migration slice may re-encode.
  *
@@ -53,14 +52,13 @@ export interface VectorsClassification {
     missing: number;
     /**
      * Ids whose unusable bytes must leave the store before a re-encode picks them up (the `limit`
-     * passed to {@link VectorRepairTarget.classifyVectors} is applied). Knowledge overwrites vectors
-     * in place, so it reports none.
+     * passed to {@link VectorRepairTarget.classifyVectors} is applied).
      */
     dropIds: readonly number[];
     /**
-     * Usable persisted vectors absent from the LIVE index, decoded and ready to re-add. Only stores
-     * whose diagnose surface tracks the live index report this (memory); knowledge rebuilds its index
-     * at open and keeps it in sync on every write, so it omits the property entirely.
+     * Usable persisted vectors absent from the LIVE index, decoded and ready to re-add. A store whose
+     * diagnose surface tracks the live index reports this; one that rebuilds its index at open and
+     * keeps it in sync on every write omits the property entirely.
      */
     unindexed?: readonly {
         id: number;
@@ -83,12 +81,17 @@ export interface VectorRepairTarget {
     semanticAvailable(): boolean;
     /** The RAW `semantic.auto_migrate` value; the flow decides what it means (`!== false`). */
     autoMigrate(): boolean | undefined;
-    /** Cheap `{ stale, space_stale, legacy? }` — blob LENGTHS only, never decodes. */
-    vectorSpaceHealth(): StaleVectorCounts;
+    /**
+     * Cheap `{ stale, space_stale, legacy? }` — blob LENGTHS only, never decodes.
+     *
+     * `Awaitable` (DB-2): the count is a repository read, and a remote backend answers asynchronously.
+     * The flow always awaits it, so the local adapter's plain value and a remote promise behave alike.
+     */
+    vectorSpaceHealth(): Awaitable<StaleVectorCounts>;
     /** Cheap count of ACTIVE rows with no persisted vector (part of `remaining`). */
-    missingVectorCount(): number;
+    missingVectorCount(): Awaitable<number>;
     /** One scan classifying what needs dropping and re-encoding; `limit` bounds `dropIds`. */
-    classifyVectors(limit: number): VectorsClassification;
+    classifyVectors(limit: number): Awaitable<VectorsClassification>;
     /**
      * Optional: put usable persisted vectors missing from the live index back into it, returning how
      * many were added. Called with the slice of {@link VectorsClassification.unindexed} the current
@@ -97,9 +100,9 @@ export interface VectorRepairTarget {
     reindexUsable?(rows: readonly {
         id: number;
         vec: Float32Array;
-    }[]): number;
+    }[]): Awaitable<number>;
     /** Clear unusable bytes (table + live index); returns how many rows were actually cleared. */
-    dropVectors(ids: readonly number[]): number;
+    dropVectors(ids: readonly number[]): Awaitable<number>;
     /** Encode + persist up to `limit` rows into the current space, one row isolated at a time. */
     reencodeVectors(limit: number): Promise<{
         encoded: number;
@@ -115,14 +118,12 @@ export interface PersistedVectorRow {
     embedding_model?: string | null;
 }
 /**
- * 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`).
+ * Rebuild the store's live vstore from its persisted rows, count what is unusable in the current
+ * space, and say so once — the "open for business" step, kept in one implementation so a change to
+ * what counts as stale cannot land in one place only.
+ *
+ * The store's ONLY half is the row read (`facts.activeVectorRows()`); the reload, the count and the
+ * loud warning live here.
  */
 export declare function loadVectorIndex(opts: {
     store: VectorRepairStore;
@@ -157,8 +158,8 @@ export interface EncodeWriteTarget {
      * Persist one group of encoded rows. Throwing fails the WHOLE group, which is what lets the store
      * decide how to reconcile its live index (see {@link onWriteError}).
      */
-    write(rows: readonly EncodedVector[]): void;
-    /** Rows per `write` call (default 1). Knowledge uses its measured `WRITE_BATCH`. */
+    write(rows: readonly EncodedVector[]): Awaitable<void>;
+    /** Rows per `write` call (default 1). */
     readonly writeBatch?: number;
     /** Called once per row whose encode (or live-index add) failed. */
     onRowError?(row: VectorEncodeRow, error: unknown): void;
@@ -168,15 +169,13 @@ export interface EncodeWriteTarget {
 /**
  * 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.
+ * The skeleton: serial encode (a MEASURED decision — a padded batched forward pass is slower on real
+ * per-row texts), `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.
+ * failed group, and the summary log.
  */
 export declare function encodeAndPersist(rows: readonly VectorEncodeRow[], target: EncodeWriteTarget): Promise<{
     encoded: number;
@@ -229,20 +228,11 @@ export interface DriveVectorRepairOptions {
  */
 export declare function driveVectorRepair(target: VectorRepairTarget, opts?: DriveVectorRepairOptions): Promise<VectorMigrationOutcome>;
 /**
- * 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).
- */
-export declare function driveVectorRepairs(targets: readonly VectorRepairTarget[], opts?: DriveVectorRepairOptions): Promise<VectorMigrationOutcome[]>;
-/**
- * The explicit, unbounded repair behind `mem_admin vectors_fix` / `avantf-mem vectors --fix`,
- * covering one or both stores.
+ * The explicit, unbounded repair behind `mem_admin vectors_fix` / `avantf-mem vectors --fix`.
  *
- * `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.
+ * `dry_run` previews every count without writing — and without loading the model (so a preview also
+ * reports `would_warm`).
  */
-export declare function vectorsFix(targets: Partial<Record<VectorRepairStore, VectorRepairTarget>>, opts: {
+export declare function vectorsFix(target: VectorRepairTarget, opts: {
     dryRun: boolean;
-    store?: VectorRepairStore;
 }): Promise<VectorsFixReport>;

package/lib/engine/mem-contract/config.d.ts

@@ -4,12 +4,11 @@ import { z } from 'zod';
  * default embedder, `Xenova/bge-small-zh-v1.5`, shares the same 512-token window — this constant
  * did NOT move when the embedder changed; only its vector width did, 512 → 768.)
  *
- * Exported because more than one default derives from it: the embedder's fallback window and
- * `knowledge.chunk_size` below. transformers.js truncates past the window SILENTLY, so every
- * derivation has to agree on the number.
+ * Exported because the embedder's fallback input window derives from it. transformers.js truncates
+ * past the window SILENTLY, so every derivation has to agree on the number.
  */
 export declare const DEFAULT_MODEL_WINDOW_TOKENS = 512;
-/** The merged runtime config shared by memory and knowledge stores. */
+/** The merged runtime config shared by the memory store and the retrieval stack. */
 export declare const ConfigSchema: z.ZodObject<{
     dataHome: z.ZodDefault<z.ZodString>;
     semantic: z.ZodPrefault<z.ZodObject<{
@@ -38,6 +37,7 @@ export declare const ConfigSchema: z.ZodObject<{
         min_semantic_similarity: z.ZodDefault<z.ZodNumber>;
         min_fts_terms: z.ZodDefault<z.ZodNumber>;
         min_jaccard: z.ZodDefault<z.ZodNumber>;
+        min_score: z.ZodDefault<z.ZodNumber>;
         leg_cap: z.ZodDefault<z.ZodNumber>;
         time_window: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
@@ -80,45 +80,51 @@ export type Config = z.infer<typeof ConfigSchema>;
 /** Built-in defaults — the lowest precedence layer. */
 export declare const defaultConfig: Config;
 /**
- * Memory store-specific config. Overrides on top of the common Config.
- * Note: `db.path` is the single authoritative path for the memory DB.
+ * The storage backend every store opens through (DB-1, docs/DATABASE_PORTABILITY.md §12).
+ *
+ * `backend` is a STRING, not an enum: an unknown value must reach the composition root and fail
+ * there with a message naming the value, rather than being silently replaced by the schema default.
+ * Built-in drivers: `sqlite` (default) and `fake` (DB-4, docs/DB_DRIVER_LAYOUT.md §五).
+ *
+ * Each driver parses its OWN section; this schema only keeps the section alive through config
+ * resolution (`storage.sqlite`, `storage.fake`, a future `storage.postgres`).
  */
-export declare const MemoryConfigSchema: z.ZodObject<{
-    db: z.ZodPrefault<z.ZodObject<{
+export declare const StorageConfigSchema: z.ZodPrefault<z.ZodObject<{
+    driver: z.ZodOptional<z.ZodString>;
+    backend: z.ZodDefault<z.ZodString>;
+    sqlite: z.ZodPrefault<z.ZodObject<{
         path: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
-}, z.core.$strip>;
-export type MemoryConfig = z.infer<typeof MemoryConfigSchema>;
-/** Knowledge store-specific config. */
-export declare const KnowledgeConfigSchema: z.ZodObject<{
+    fake: z.ZodOptional<z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        latency_ms: z.ZodOptional<z.ZodNumber>;
+        fail_after: z.ZodOptional<z.ZodNumber>;
+        fail_message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+export type StorageConfig = z.infer<typeof StorageConfigSchema>;
+/**
+ * Memory store-specific config. Overrides on top of the common Config.
+ *
+ * `storage.backend` is the composition-root switch (default `sqlite`). `storage.sqlite.path` is the
+ * SQLite file; `db.path` remains as its legacy alias so an existing `memory.yaml` keeps working.
+ */
+export declare const MemoryConfigSchema: z.ZodObject<{
     db: z.ZodPrefault<z.ZodObject<{
         path: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
-    docs: z.ZodPrefault<z.ZodObject<{
-        dir: z.ZodDefault<z.ZodString>;
-    }, z.core.$strip>>;
-    git: z.ZodPrefault<z.ZodObject<{
-        mode: z.ZodDefault<z.ZodEnum<{
-            auto: "auto";
-            off: "off";
-        }>>;
-        root: z.ZodDefault<z.ZodString>;
-        ignore: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    }, z.core.$strip>>;
-    open: z.ZodPrefault<z.ZodObject<{
-        editor: z.ZodDefault<z.ZodString>;
-    }, z.core.$strip>>;
-    domains: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    chunk_size: z.ZodDefault<z.ZodNumber>;
-    chunk_overlap: z.ZodDefault<z.ZodNumber>;
-    source_priority: z.ZodDefault<z.ZodEnum<{
-        workspace: "workspace";
-        none: "none";
-    }>>;
-    ingest: z.ZodPrefault<z.ZodObject<{
-        local_roots: z.ZodDefault<z.ZodArray<z.ZodString>>;
-        allow_outside_workspace: z.ZodDefault<z.ZodBoolean>;
-        allow_private_network: z.ZodDefault<z.ZodBoolean>;
+    storage: z.ZodPrefault<z.ZodObject<{
+        driver: z.ZodOptional<z.ZodString>;
+        backend: z.ZodDefault<z.ZodString>;
+        sqlite: z.ZodPrefault<z.ZodObject<{
+            path: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>;
+        fake: z.ZodOptional<z.ZodObject<{
+            path: z.ZodOptional<z.ZodString>;
+            latency_ms: z.ZodOptional<z.ZodNumber>;
+            fail_after: z.ZodOptional<z.ZodNumber>;
+            fail_message: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export type KnowledgeConfig = z.infer<typeof KnowledgeConfigSchema>;
+export type MemoryConfig = z.infer<typeof MemoryConfigSchema>;

package/lib/engine/mem-contract/text.d.ts

@@ -12,7 +12,7 @@
  *
  * ── THE ORIGINAL IS THE BASE KIT ──────────────────────────────────────────────────────────────
  *
- * `base/plugin-base/src/kit/wellformed.ts` owns `wellFormedText` / `wellFormedDeep` (interface v2)
+ * `base/src/kit/wellformed.ts` owns `wellFormedText` / `wellFormedDeep` (interface v2)
  * and is the copy ONE base release fixes for the whole family. This module is its **deliberate
  * mirror**, in the same sense as `./family.ts` (whose original is the base's `kit/family.ts`): the
  * engine (`@avantf/mem`) and the CLI / MCP faces have **no DSH host and never load the base**