@avantf/dsh-mem 0.6.3 → 0.7.0

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

@@ -6,6 +6,8 @@ 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';
 export interface RuntimeOptions {
     dataHome?: string;
     memoryDbPath?: string;
@@ -35,6 +37,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.
@@ -65,6 +83,28 @@ export type DispatchError = {
  * admin payload no store method produces, because the runtime composes it.
  */
 export type AdminStatsResult = StatsSummary;
+/**
+ * `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 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 the four hits-returning recall actions, which one overload groups because a
  * caller may hold them as a union (`action: 'chain' | 'reason'`).
@@ -119,9 +159,10 @@ export type RecallDispatch = {
     (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, {
@@ -163,6 +204,19 @@ export type AdminDispatch = {
     (req: Extract<AdminRequest, {
         action: 'maintenance';
     }>): StoreResult<MemoryStore, 'maintenance'>;
+    (req: Extract<AdminRequest, {
+        action: 'export';
+    }>): AdminExportReport;
+    /** Content-detected: a SQLite source answers with the db report, an export document with the JSON one. */
+    (req: Extract<AdminRequest, {
+        action: 'import';
+    }>): Promise<ImportReport | MergeReport>;
+    (req: Extract<AdminRequest, {
+        action: 'merge';
+    }>): Promise<MergeReport>;
+    (req: Extract<AdminRequest, {
+        action: 'restore_snapshot';
+    }>): Promise<AdminRestoreSnapshotReport>;
     (req: AdminRequest): unknown;
 };
 /**

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

@@ -0,0 +1,116 @@
+/**
+ * Full-fidelity REBUILD of a memory library from an export document — the ONE owner of
+ * `avantf-mem restore <file>`.
+ *
+ * RESTORE IS NOT IMPORT. `import` / `merge` (see `facts_io.ts`) are CONTENT-IDENTITY UNIONS: new
+ * rows get new ids, only ACTIVE facts travel, and every value the document carries beyond
+ * category/ttl/sources/validity is counted as dropped. Restore is the opposite promise — "put this
+ * library back exactly as it was" — which is only answerable if the target is EMPTY:
+ *
+ *   - `facts` is written DIRECTLY, one transaction, keeping `fact_id`, status, timestamps,
+ *     `trust_score`, `settle_clock`, counters, pin state, TTL, validity, the supersedes pointer and
+ *     the mirror bookkeeping. A non-empty target is REFUSED (never merged into), because "restore"
+ *     that silently unions two histories is a different, unreviewable operation.
+ *   - Rows are inserted in `source_id` ASCENDING order, so the row a `supersedes` pointer names
+ *     already exists when the pointer is written. v1 documents carry the same pointer as
+ *     `supersedes_source_id`, so both versions resolve identically.
+ *   - `fact_sources` is restored IN FULL (a fact may carry several rows); the identity `import`
+ *     is forced to collapse into one `ref` string is not a limitation restore inherits.
+ *   - FTS is NOT written by hand. `facts_fts` is an external-content FTS5 table with AFTER INSERT /
+ *     DELETE / UPDATE triggers (`db/schema.ts`), so inserting into `facts` indexes the row. That is
+ *     the whole reason this path can bypass `MemoryStore.add` without losing lexical recall.
+ *   - The DERIVED state is re-derived, not restored. `entities_version = 0` marks every row for the
+ *     entity sweep, which rebuilds `fact_entities`, `triples` and the HRR bundle in bounded passes
+ *     after the commit; `conflict_checked = 1` keeps a restored corpus from queueing a whole-library
+ *     conflict re-scan (the log is not exported — see below).
+ *   - VECTORS ARE NOT RESTORED (`semantic_vector`, `embedding_model` stay NULL, `hrr_vector` stays
+ *     NULL until the sweep writes it). They are machine-local encodings of a specific model revision;
+ *     copying them between hosts would create a vector space the live index cannot serve. The report
+ *     says so and points at `avantf-mem vectors --fix` / a host restart.
+ *
+ * WHAT IS DELIBERATELY NOT RESTORED: `contradiction_log`, the retrieval-stat meta table, `tags`
+ * (not exported), and `archived_clock`. The last one is a TRUST-CLOCK value ("active days at archive
+ * time"); the document only carries `archived_at` (a wall-clock timestamp), and converting one into
+ * the other would invent data. Leaving it NULL sends restored archived rows down
+ * `purgeArchived`'s CALENDAR branch, which reads the restored `archived_at` — the honest
+ * approximation, and the reason a restore does not restart every purge countdown at zero.
+ *
+ * V1 DOCUMENTS ARE READ. v2 only ADDED optional facts columns, so a v1 row simply lacks them; each
+ * absence is counted per field in `metadata_missing` and resolved with the documented fallback. The
+ * one fallback with a real decision behind it: `settle_clock` becomes the CURRENT active-day clock.
+ * Zero would make every restored fact decay by the host's whole clock in one settlement; the current
+ * clock is the "no decay has happened yet" baseline, which is what a fresh restore means.
+ *
+ * @module store/facts_restore
+ */
+import type { FactsExportDocument } from '../facts_io.js';
+import type { Db } from '../db/conn.js';
+import { type EntitySweepReport } from './entity_sweep.js';
+/** The one operator hint about the data restore cannot carry. */
+export declare const RESTORE_VECTOR_HINT: string;
+/**
+ * Every metadata field the report accounts for.
+ *
+ * The list is the DOCUMENT's, not the table's: it includes the v2 additions (so a v1 file shows
+ * exactly which columns it could not carry) and the derived-state stamps (which restore re-derives
+ * rather than trust). A field counts as missing when the document does not carry the key at all —
+ * `null` is a value the document states ("unknown"), not an absence.
+ */
+export declare const RESTORE_METADATA_FIELDS: readonly ["category", "created_at", "updated_at", "trust_score", "pinned", "pinned_at", "assert_count", "helpful_count", "last_reinforced_at", "ttl_days", "valid_from", "valid_to", "supersedes_source_id", "archive", "sources", "settle_clock", "bonus_count", "bonus_window_at", "retrieval_count", "last_retrieved_at", "mirror_source", "mirror_target", "entities_version", "conflict_checked"];
+export type RestoreMetadataField = (typeof RESTORE_METADATA_FIELDS)[number];
+/** Per-field count of facts whose document did not carry that field. */
+export type RestoreMetadataMissing = Record<RestoreMetadataField, number>;
+export interface RestoreOptions {
+    /** Plan only: no write, no entity rebuild; the report carries `would_restore` + `target_facts`. */
+    dryRun?: boolean;
+}
+/**
+ * The store's half of the contract, narrow on purpose: the ONE write connection, plus the bounded
+ * entity sweep this flow reuses after the commit. Nothing here knows about `MemoryStore`.
+ */
+export interface RestoreTarget {
+    db: Db;
+    reindexEntities(budget?: number): Promise<EntitySweepReport>;
+}
+/** How many facts a document would restore, split by status. */
+export interface RestoreCounts {
+    total: number;
+    active: number;
+    archived: number;
+}
+/** The single JSON object the CLI prints (it adds `file` / `codec`, which are argv facts). */
+export interface RestoreReport {
+    /** The DOCUMENT's version, echoed as-is (1 or 2). */
+    version: number;
+    /** Present on `--dry-run` only. */
+    dry_run?: true;
+    /** Present on `--dry-run` only: what a real run would write. */
+    would_restore?: RestoreCounts;
+    /**
+     * Present on `--dry-run` only: the target's CURRENT fact count. Non-zero means the real run would
+     * be refused (restore only rebuilds into an empty table).
+     */
+    target_facts?: number;
+    /** Facts actually written (0 on a dry run). */
+    restored: number;
+    active: number;
+    archived: number;
+    metadata_missing: RestoreMetadataMissing;
+    /** FTS5 rows after the commit — the trigger's work, asserted equal to `restored` by the tests. */
+    fts_rows: number;
+    entities: EntitySweepReport;
+    vectors: {
+        restored: 0;
+        hint: string;
+    };
+}
+/**
+ * Rebuild the target library from `doc`.
+ *
+ * Order of guarantees: the document is validated COMPLETELY first (no writes on a bad file), then one
+ * `BEGIN IMMEDIATE` transaction re-checks emptiness and inserts facts + sources (a failure anywhere
+ * rolls the whole thing back), and only after that commit does the derived state get rebuilt. The
+ * entity sweep is deliberately OUTSIDE the transaction: it is bounded, resumable work, and holding
+ * the write lock for a whole-corpus re-extraction is exactly what its batch exists to avoid.
+ */
+export declare function restoreFactsDocument(target: RestoreTarget, doc: FactsExportDocument, options?: RestoreOptions): Promise<RestoreReport>;

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/memory.d.ts

@@ -1,6 +1,8 @@
 import { type Config, type ContradictionRecord, type FactDetail, type FactPage, type FloorProfile, type RecallResult, type RememberResult, type SourceCoverage, type TrustDiagnostic, type ValidityCoverage, type VectorMigrationOutcome, type VectorMigrationProgress, type VectorSpaceHealth, type VectorsDiagnostic, type VectorsFixStoreReport } from '../../mem-contract/index.js';
 import type { SemanticBackend, VectorStore } from '../../mem-retrieval/index.js';
 import { ENTITY_SWEEP_BATCH, type EntitySweepReport } from './entity_sweep.js';
+import { type RestoreOptions, type RestoreReport } from './facts_restore.js';
+import type { FactsExportDocument } from '../facts_io.js';
 import { DEFAULT_VECTOR_MIGRATION_BATCH, type VectorRepairTarget } from './vector_repair.js';
 import type { Db } from '../db/conn.js';
 import { type LexicalProbe } from './lexical.js';
@@ -487,6 +489,20 @@ export declare class MemoryStore {
      * selection (`facts.staleEntityRows`, ACTIVE facts only) and the per-fact write below.
      */
     reindexEntities(budget?: number): Promise<EntitySweepReport>;
+    /**
+     * Rebuild this library from an export document — the engine half of `avantf-mem restore <file>`.
+     *
+     * A THIN adapter on purpose: the empty-table rule, the insert order, the SQL and the report all
+     * live in `store/facts_restore.ts`, because this class is a hub and a rebuild of the whole facts
+     * table must not become another reason to grow it. What it contributes is the two things only the
+     * store has: the ONE write connection (so the restored rows are immediately visible to every
+     * reader here) and the derived-state entity sweep that runs after the commit.
+     *
+     * Reachable from `mem_admin restore_snapshot` (and from the CLI): after a real restore this
+     * method refreshes the live vector index and resets the conflict-drain cursor, so a host that
+     * rebuilt its library from a tool call answers from the NEW rows without a restart.
+     */
+    restoreFacts(doc: FactsExportDocument, options?: RestoreOptions): Promise<RestoreReport>;
     /**
      * A fact left the ACTIVE corpus: retire the open conflicts that name it, so
      * `contradict` never reports a pair whose revision is archived and repeated

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/engine/mem-contract/tools.d.ts

@@ -48,6 +48,13 @@ export declare const FACT_VIEW_ADMIN_ACTIONS: readonly ["list", "detail"];
  * explicitly with `mem_admin`'s diagnostic actions.
  */
 export declare function modelFacingToolResult(toolKey: string, action: unknown, value: unknown): unknown;
+/**
+ * The statuses an export may narrow to. Declared here (next to the tool schema that exposes it) so
+ * the core export path, the CLI flag validation and the admin action read ONE set: a value added
+ * here moves the contract, the CLI and the engine together.
+ */
+export declare const EXPORT_STATUSES: readonly ["active", "archived", "all"];
+export type ExportStatus = (typeof EXPORT_STATUSES)[number];
 export declare const REMEMBER_ACTIONS: readonly ["add", "update", "remove", "helpful", "unhelpful"];
 export declare const RememberUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     action: z.ZodLiteral<"add">;
@@ -78,6 +85,13 @@ export declare const RememberUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     fact_id: z.ZodNumber;
 }, z.core.$strip>], "action">;
 export type RememberRequest = z.infer<typeof RememberUnion>;
+/**
+ * The writes the model may make. `helpful` / `unhelpful` are operator feedback: the model cannot
+ * observe the retention clocks they move, and a model that could would be able to "refresh" a fact by
+ * voting on it — the exact behaviour the retention policy exists to prevent.
+ */
+export declare const MODEL_REMEMBER_ACTIONS: readonly ["add", "update", "remove"];
+export declare const ModelRememberUnion: z.ZodDiscriminatedUnion<readonly z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>[], string>;
 export declare const RECALL_ACTIONS: readonly ["search", "ask", "chain", "probe", "reason", "related", "contradict"];
 export declare const RecallUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     action: z.ZodLiteral<"search">;
@@ -125,7 +139,14 @@ export declare const RecallUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     limit: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>], "action">;
 export type RecallRequest = z.infer<typeof RecallUnion>;
-export declare const ADMIN_ACTIONS: readonly ["stats", "list", "detail", "archive", "restore", "pin", "unpin", "trust_diagnose", "vectors_diagnose", "vectors_fix", "contradict_check", "contradict_resolve", "maintenance"];
+/**
+ * The retrieval actions the model may call. `chain` and `related` are operator graph views
+ * (the settings page and the CLI use them); the model reaches the same facts through
+ * `search`/`probe`/`ask`/`reason`, so the two graph shapes are not part of its tool.
+ */
+export declare const MODEL_RECALL_ACTIONS: readonly ["search", "ask", "probe", "reason", "contradict"];
+export declare const ModelRecallUnion: z.ZodDiscriminatedUnion<readonly z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>[], string>;
+export declare const ADMIN_ACTIONS: readonly ["stats", "list", "detail", "archive", "restore", "pin", "unpin", "trust_diagnose", "vectors_diagnose", "vectors_fix", "contradict_check", "contradict_resolve", "maintenance", "export", "import", "merge", "restore_snapshot"];
 export declare const AdminUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     action: z.ZodLiteral<"stats">;
 }, z.core.$strip>, z.ZodObject<{
@@ -177,8 +198,41 @@ export declare const AdminUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     loser_fact_id: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"maintenance">;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"export">;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        archived: "archived";
+        all: "all";
+    }>>;
+    file: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"import">;
+    file: z.ZodString;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"merge">;
+    file: z.ZodString;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"restore_snapshot">;
+    file: z.ZodString;
+    confirm: z.ZodLiteral<true>;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>], "action">;
 export type AdminRequest = z.infer<typeof AdminUnion>;
+/**
+ * The admin actions the model may call: a fact page plus the backup/restore family.
+ *
+ * Everything else is OPERATOR machinery: diagnostics and repairs (the model cannot see trust values
+ * and must not rerun the embedding strategy), curation (pin/archive/contradiction verdicts), and
+ * duplicates of what is already model-facing (`detail` is a single-fact view of the same page;
+ * `contradict_check` is the write-side half of `mem_recall.contradict`; `merge` is what `import`
+ * now does automatically for a SQLite file). The full union stays for the runtime, the Remote
+ * gateway (the settings page drives every action) and the CLI.
+ */
+export declare const MODEL_ADMIN_ACTIONS: readonly ["list", "export", "import", "restore_snapshot"];
+export declare const ModelAdminUnion: z.ZodDiscriminatedUnion<readonly z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>[], string>;
 /** The `source` a write gets when it omits one; a document's identity is `(domain, source, title)`. */
 export declare const DEFAULT_KB_SOURCE = "default";
 export declare const KbUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{