@avantf/dsh-mem 0.6.4 → 0.8.0

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

@@ -1,11 +1,23 @@
-import type { AdminRequest, KbAddRequest, KbConflictReport, KbRequest, QueryRequest, RecallRequest, RecallResult, RememberRequest, VectorsFixReport } from '../mem-contract/index.js';
+import type { AdminRequest, RecallRequest, RememberRequest, VectorsFixReport } 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';
+import { type FactsExportCodec, type ImportReport, type MergeReport } from './facts_io.js';
+import type { RestoreReport } from './store/facts_restore.js';
+/**
+ * The write rules a MODEL-FACING boundary adds on top of the contract (JOURNAL_TITLE_SEARCH §2.3).
+ *
+ * There is exactly one today: "a journal add must carry a title" cannot be expressed in zod's
+ * discriminated union without wrapping a branch in `superRefine`, which would break the JSON-Schema /
+ * DSH-parameter derivation (both read the branch's `.shape`). So it is enforced at the tool handler
+ * (`runToolSpec` → `dispatchToolKey`) and passed down as a store rule. It is deliberately NOT a
+ * store-wide invariant: old journals, old exports, the CLI and scripts all write untitled facts.
+ */
+export interface RememberWriteRules {
+    requireJournalTitle?: boolean;
+}
 export interface RuntimeOptions {
     dataHome?: string;
     memoryDbPath?: string;
@@ -35,6 +47,22 @@ export interface RuntimeOptions {
         readonly tools?: string;
         readonly models?: string;
     };
+    /**
+     * Skip the adapters' eager constructor warm even when the caller passes no {@link managedRoots}:
+     * the caller owns the warm schedule and will warm explicitly.
+     *
+     * There are exactly TWO ways to get a deferred warm, and both are requests of the same thing:
+     *
+     *   - {@link managedRoots} — the DSH plugin's path. The framework owns the model root and may still
+     *     be installing into it, so the backends must not warm themselves (that would race the install
+     *     and fetch a second copy).
+     *   - `deferWarm: true` — the CLI's path. The flag exists because the CLI is one-shot and its
+     *     READ-ONLY commands (`stats`, `list`, `export`, …) must not load or download the model at all;
+     *     it warms explicitly, and only from `needsModels` (the command table in `cli/src/index.ts`).
+     *
+     * A first `encode()` still warms lazily, so deferring never costs the commands that do encode.
+     */
+    deferWarm?: boolean;
 }
 /**
  * The awaited result of a store method — what a dispatch overload promises.
@@ -66,15 +94,34 @@ export type DispatchError = {
  */
 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`.)
+ * `admin export`: the file THIS call wrote and its container. Deliberately carries NO document body
+ * — the model gets a receipt, not the library (the file is the artifact; whoever needs the facts
+ * reads it with the CLI or imports it back).
  */
-export type RecallHitsResult = StoreResult<MemoryStore, 'search'>;
+export interface AdminExportReport {
+    file: string;
+    codec: FactsExportCodec;
+    bytes: number;
+    plain_bytes: number;
+    counts: {
+        active: number;
+        archived: number;
+    };
+    /** True when an existing file was replaced (the atomic write is the same either way). */
+    overwritten: boolean;
+}
+/** `admin restore_snapshot`: the engine's restore report plus the container it came from. */
+export type AdminRestoreSnapshotReport = RestoreReport & {
+    file: string;
+    codec: FactsExportCodec;
+};
+/**
+ * The payload of `mem_recall.search`: the two-stage result (an exact page or a fuzzy shortlist).
+ * Named from the store method that produces it, so a change there cannot leave this alias lying.
+ */
+export type RecallHitsResult = StoreResult<MemoryStore, 'searchMemory'>;
+/** The payload of `mem_recall.titles`: an exact page or a fuzzy shortlist of title candidates. */
+export type RecallTitlesResult = StoreResult<MemoryStore, 'titles'>;
 /**
  * `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
@@ -85,148 +132,128 @@ export type RecallHitsResult = StoreResult<MemoryStore, 'search'>;
 export type RememberDispatch = {
     (req: Extract<RememberRequest, {
         action: 'add';
-    }>): Promise<StoreResult<MemoryStore, 'add'>>;
+    }>, rules?: RememberWriteRules): Promise<StoreResult<MemoryStore, 'add'>>;
     (req: Extract<RememberRequest, {
         action: 'update';
-    }>): Promise<StoreResult<MemoryStore, 'update'>>;
+    }>, rules?: RememberWriteRules): 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>;
+    (req: RememberRequest, rules?: RememberWriteRules): 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.
+ * Same per-action idea as {@link RememberDispatch}, over the TWO public recall actions
+ * (docs/RECALL_INTERFACE.md §1): a content search answers hits (exact page or fuzzy shortlist), a
+ * title search answers candidates. Two different payload shapes, so two overloads.
  */
 export type RecallDispatch = {
     (req: Extract<RecallRequest, {
-        action: 'search' | 'probe' | 'chain' | 'reason';
+        action: 'search';
     }>): 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'>>;
+        action: 'titles';
+    }>): Promise<RecallTitlesResult>;
     (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.
+ * `admin` is the widest dispatcher: counts, a fact page, a detail, flags, five diagnostic
+ * reports, and the four data-root maintenance actions (export / import / merge / restore_snapshot).
+ * `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;
+    }>): Promise<AdminStatsResult>;
     (req: Extract<AdminRequest, {
         action: 'list';
-    }>): StoreResult<MemoryStore, 'list'>;
+    }>): Promise<StoreResult<MemoryStore, 'list'>>;
     (req: Extract<AdminRequest, {
         action: 'detail';
-    }>): StoreResult<MemoryStore, 'get'> | DispatchError;
+    }>): Promise<StoreResult<MemoryStore, 'get'> | DispatchError>;
     (req: Extract<AdminRequest, {
         action: 'archive';
-    }>): StoreResult<MemoryStore, 'archive'>;
+    }>): Promise<StoreResult<MemoryStore, 'archive'>>;
     (req: Extract<AdminRequest, {
         action: 'restore';
-    }>): StoreResult<MemoryStore, 'restore'>;
+    }>): Promise<StoreResult<MemoryStore, 'restore'>>;
     (req: Extract<AdminRequest, {
         action: 'pin';
-    }>): StoreResult<MemoryStore, 'pin'>;
+    }>): Promise<StoreResult<MemoryStore, 'pin'>>;
     (req: Extract<AdminRequest, {
         action: 'unpin';
-    }>): StoreResult<MemoryStore, 'unpin'>;
+    }>): Promise<StoreResult<MemoryStore, 'unpin'>>;
     (req: Extract<AdminRequest, {
         action: 'trust_diagnose';
-    }>): StoreResult<MemoryStore, 'trustDiagnose'>;
+    }>): Promise<StoreResult<MemoryStore, 'trustDiagnose'>>;
     (req: Extract<AdminRequest, {
         action: 'vectors_diagnose';
-    }>): StoreResult<MemoryStore, 'vectorsDiagnose'>;
+    }>): Promise<StoreResult<MemoryStore, 'vectorsDiagnose'>>;
     (req: Extract<AdminRequest, {
         action: 'vectors_fix';
     }>): Promise<VectorsFixReport>;
     (req: Extract<AdminRequest, {
         action: 'contradict_check';
-    }>): StoreResult<MemoryStore, 'checkContradictions'>;
+    }>): Promise<StoreResult<MemoryStore, 'checkContradictions'>>;
+    (req: Extract<AdminRequest, {
+        action: 'contradictions';
+    }>): Promise<StoreResult<MemoryStore, 'listContradictions'>>;
     (req: Extract<AdminRequest, {
         action: 'contradict_resolve';
-    }>): StoreResult<MemoryStore, 'resolveContradiction'>;
+    }>): Promise<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, {
+    }>): Promise<StoreResult<MemoryStore, 'maintenance'>>;
+    (req: Extract<AdminRequest, {
+        action: 'export';
+    }>): Promise<AdminExportReport>;
+    /** Content-detected: a SQLite source answers with the db report, an export document with the JSON one. */
+    (req: Extract<AdminRequest, {
         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>;
+    }>): Promise<ImportReport | MergeReport>;
+    (req: Extract<AdminRequest, {
+        action: 'merge';
+    }>): Promise<MergeReport>;
+    (req: Extract<AdminRequest, {
+        action: 'restore_snapshot';
+    }>): Promise<AdminRestoreSnapshotReport>;
+    (req: AdminRequest): 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).
+     * The conditional hint's decision (DESIGN §12): would a memory retrieval return at least one hit
+     * for `text`? Implemented as `MemoryStore.search({ query: text, limit: 1, probe: true })` and
+     * answering `hits.length > 0` — there is no second threshold, no lexical short-circuit and no
+     * self-query special case here: retrieval already augments the query with its own rewrite.
+     *
+     * READ-ONLY is a contract: this runs on the user-message path and must never reinforce a fact,
+     * record retrieval/usage stats, warm/download a model, or mutate the vstore/DB. Never throws — a
+     * missing hint is harmless while a throwing `agent/pre-step` listener takes the step down.
      */
-    relevance(text: string): RelevanceHit;
+    wouldFind(text: string): Promise<boolean>;
     /**
      * 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;
+    shutdown(): Promise<void>;
 }
-/** Build the runtime: load config, open the memory DB, construct the stores. */
-export declare function buildRuntime(opts?: RuntimeOptions): AvantfRuntime;
+/**
+ * Build the runtime: load config, open memory DB, construct the stores, run their open-time pass.
+ *
+ * ASYNC since DB-2: the store's startup pass (clock repair, lifecycle tick, vector-index reload) now
+ * awaits repository reads, so it cannot run inside a constructor. Making the open await it keeps the
+ * ordering every caller depends on — by the time `buildRuntime` resolves, the store is started.
+ */
+export declare function buildRuntime(opts?: RuntimeOptions): Promise<AvantfRuntime>;

package/lib/engine/mem/storage/create.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The storage composition root (DB-1; registry-based from DB-2/DB-3).
+ *
+ * One decision, made once: which driver serves this process. The configured name is resolved through
+ * the REGISTRY, so adding a storage is adding a driver package — never a new branch here
+ * (docs/DB_DRIVER_LAYOUT.md §一 rule "不要新增其他固定 backend 分支"). An unknown name fails
+ * explicitly and creates nothing; there is no silent SQLite fallback.
+ *
+ * The builtin drivers are imported below for their REGISTRATION side effect: this file is the
+ * factory, so the factory is where the builtins must be available, no matter which module graph the
+ * host loaded. `fake` is a builtin on purpose (DB-4, docs/DB_DRIVER_LAYOUT.md §五): it exists so the
+ * config switch and the async boundary can be exercised end to end without a second storage engine,
+ * which is why selecting it needs no import at the call site.
+ *
+ * @module storage/create
+ */
+import type { StorageConfig } from '../../mem-contract/index.js';
+import type { StorageBackend } from '../interfaces/storage_backend.js';
+import '../dbdrivers/sqlite/index.js';
+import '../dbdrivers/fake/index.js';
+/** Raised when `storage.backend` (or `storage.driver`) names a driver this host does not have. */
+export declare class UnknownStorageBackendError extends Error {
+    readonly backend: string;
+    constructor(backend: string);
+}
+export interface CreateStorageBackendOptions {
+    /**
+     * The configured contradiction threshold (`lifecycle.contradiction_threshold`), passed to the
+     * driver for its detector construction.
+     */
+    readonly contradictionThreshold?: number;
+}
+/**
+ * Open the selected driver.
+ *
+ * ASYNC because every driver's `open` is (DB-2): the SQLite driver resolves immediately, a remote one
+ * connects. Callers await it, so the host has one opening path.
+ *
+ * @throws {UnknownStorageBackendError} when the configured name has no registered driver.
+ * @throws {UnsupportedStorageContractError} when the driver's contract major is not supported.
+ */
+export declare function createStorageBackend(config: StorageConfig, options?: CreateStorageBackendOptions): Promise<StorageBackend>;

package/lib/engine/mem/storage/errors.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The storage error boundary (DB-3).
+ *
+ * SQLite reports failures as a driver error object with a numeric `errcode`; PostgreSQL has SQLSTATE,
+ * an HTTP backend has status codes, and none of those belong above the port. The store has exactly
+ * three things it can usefully do with a failed read/write: retry (the backend is temporarily
+ * unavailable), report a conflict (a uniqueness/constraint rule refused the write), or fail (anything
+ * else). This module names those three, and `db/sqlite.ts` — the one place that sees a driver error —
+ * maps into them.
+ *
+ * WHAT THIS IS NOT: a replacement for the domain refusals. `TITLE_IMMUTABLE`, `RELATIONS_NEED_NOTE`
+ * and the other `Error`s the store throws are decisions about the caller's request, not backend
+ * failures; they stay plain and unchanged. Only errors that come out of the database layer are
+ * classified here.
+ *
+ * The messages are preserved verbatim (the classification is metadata), so every existing caller and
+ * test that asserts on a driver message keeps working.
+ *
+ * @module storage/errors
+ */
+/** What a caller can do about a failed storage operation. */
+export type StorageFailureKind = 'unavailable' | 'constraint' | 'corrupt' | 'unknown';
+/** A database-layer failure, classified so the boundary does not leak a driver's error shape. */
+export declare class StorageError extends Error {
+    readonly kind: StorageFailureKind;
+    constructor(message: string, kind: StorageFailureKind, options?: {
+        code?: string | number;
+        cause?: unknown;
+    });
+    /** The driver's own code, kept for a log line — never branched on above the adapter. */
+    readonly code?: string | number;
+    /** Whether the same call may succeed if repeated later (a lock timeout, a restarting server). */
+    get retryable(): boolean;
+}
+/** The backend is temporarily unable to serve (SQLite: `SQLITE_BUSY`/`SQLITE_LOCKED`). */
+export declare class StorageUnavailableError extends StorageError {
+    constructor(message: string, options?: {
+        code?: string | number;
+        cause?: unknown;
+    });
+}
+/** The backend refused the write because of one of its integrity rules. */
+export declare class StorageConstraintError extends StorageError {
+    constructor(message: string, options?: {
+        code?: string | number;
+        cause?: unknown;
+    });
+}
+/** The stored data cannot be read (SQLite: `SQLITE_CORRUPT`/`SQLITE_NOTADB`). */
+export declare class StorageCorruptError extends StorageError {
+    constructor(message: string, options?: {
+        code?: string | number;
+        cause?: unknown;
+    });
+}
+/** Whether a caught value is already one of ours (a second mapping must not wrap it again). */
+export declare function isStorageError(error: unknown): error is StorageError;
+/**
+ * Classify a driver failure into the storage vocabulary.
+ *
+ * Takes `unknown` because that is what a `catch` binds; anything already classified is returned
+ * untouched (mapping is idempotent), and a non-error value becomes a generic `StorageError` carrying
+ * its string form, so callers never have to re-check.
+ */
+export declare function mapStorageError(error: unknown): StorageError;

package/lib/engine/mem/storage/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The storage boundary's public entry point (DB-1; registry factory since DB-2/DB-3).
+ *
+ * It re-exports the HAL CONTRACT (`interfaces/`) for the store and for external drivers, and the
+ * registry/factory that select a driver. It deliberately re-exports NO driver implementation: a
+ * caller that wants the SQLite backend imports `dbdrivers/sqlite` explicitly (turning a hidden
+ * dependency into a visible one), while `createStorageBackend` serves everyone else through the
+ * registry.
+ *
+ * @module storage
+ */
+export * from '../interfaces/index.js';
+export type { StorageConfig } from '../../mem-contract/index.js';
+export { assertSupportedDriver, lookupStorageDriver, registerStorageDriver, storageDriverNames, UnsupportedStorageContractError, } from './registry.js';
+export { createStorageBackend, UnknownStorageBackendError, type CreateStorageBackendOptions } from './create.js';