@avantf/dsh-mem 0.4.2 → 0.6.1

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

@@ -0,0 +1,248 @@
+/**
+ * The ONE vector-space repair flow both stores run.
+ *
+ * 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
+ * semantic leg must not serve them. `common.ts` owns the cheap DETECTION (`reportStaleVectors`); this
+ * module owns the REPAIR — a bounded, resumable, switchable loop that re-encodes the corpus in
+ * 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.
+ *
+ * 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 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.
+ *
+ * @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 StaleVectorCounts } from './common.js';
+/** The two stores this flow can drive. */
+export type VectorRepairStore = 'memory' | 'knowledge';
+/**
+ * Rows one background vector-space migration slice may re-encode.
+ *
+ * Small on purpose: the point of batching is that a query arriving mid-migration waits for at most
+ * one ONNX forward pass batch, not for a whole corpus. At ~30 ms per bge-base-zh encode a batch of 16
+ * is well under a second of contested model time, and the event loop is yielded between batches
+ * (`yieldToEventLoop`). The value is a default, not a promise — `migrateVectorSlice` takes whatever
+ * the caller needs.
+ */
+export declare const DEFAULT_VECTOR_MIGRATION_BATCH = 16;
+/**
+ * What one store's persisted-vector scan found, before any write.
+ *
+ * `stale` and `space_stale` mirror the cheap detection counts (`StaleVectorCounts`); `missing` is
+ * "ACTIVE row with no persisted vector at all" — the third reason the semantic leg cannot use a row.
+ */
+export interface VectorsClassification {
+    /** ACTIVE rows whose persisted vector has the wrong width (it cannot even be decoded). */
+    stale: number;
+    /** ACTIVE rows whose usable-width vector was recorded in another space. */
+    space_stale: number;
+    /** ACTIVE rows with no persisted vector at all. */
+    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.
+     */
+    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.
+     */
+    unindexed?: readonly {
+        id: number;
+        vec: Float32Array;
+    }[];
+}
+/**
+ * One store's half of the repair flow — the "key methods" of the template.
+ *
+ * Every method is a PRIMITIVE the store can answer from its own DAO; none of them contains the
+ * loop, the batch size or the switch logic (those are in this module, once).
+ */
+export interface VectorRepairTarget {
+    readonly store: VectorRepairStore;
+    /** The manual entry the stale-vector warning points at, as the operator would type it. */
+    readonly manualEntry: string;
+    /** The representation fingerprint this store writes into now. */
+    vectorSpace(): string;
+    /** Is the embedding model loaded RIGHT NOW? (Never warms — the flow owns the warmup policy.) */
+    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 count of ACTIVE rows with no persisted vector (part of `remaining`). */
+    missingVectorCount(): number;
+    /** One scan classifying what needs dropping and re-encoding; `limit` bounds `dropIds`. */
+    classifyVectors(limit: number): 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
+     * `limit` allows, so the flow does not re-scan the corpus for it.
+     */
+    reindexUsable?(rows: readonly {
+        id: number;
+        vec: Float32Array;
+    }[]): number;
+    /** Clear unusable bytes (table + live index); returns how many rows were actually cleared. */
+    dropVectors(ids: readonly number[]): number;
+    /** Encode + persist up to `limit` rows into the current space, one row isolated at a time. */
+    reencodeVectors(limit: number): Promise<{
+        encoded: number;
+        failed: number;
+    }>;
+    /** Optional: wait for the embedding model (explicit repair only; the background never waits). */
+    warmup?(): Promise<boolean>;
+}
+/** A persisted vector row as read back from a store, for the shared open-time load. */
+export interface PersistedVectorRow {
+    id: number;
+    vec: Uint8Array | null;
+    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`).
+ */
+export declare function loadVectorIndex(opts: {
+    store: VectorRepairStore;
+    vstore: VectorStore;
+    rows: readonly PersistedVectorRow[];
+    space: string;
+    manualEntry: string;
+}): StaleVectorCounts;
+/** One row the shared encode flow should turn into a vector. */
+export interface VectorEncodeRow {
+    id: number;
+    text: string;
+}
+/** One encoded row ready to be persisted. */
+export interface EncodedVector {
+    id: number;
+    bytes: Buffer;
+}
+/**
+ * One store's half of {@link encodeAndPersist}: how to encode, where the live index is, and how a
+ * group of vectors is persisted.
+ */
+export interface EncodeWriteTarget {
+    readonly store: VectorRepairStore;
+    /** The space recorded beside every persisted vector. */
+    readonly space: string;
+    /** One text → vector. Throwing skips that row (never the group). */
+    encode(text: string): Promise<Float32Array>;
+    /** Add a freshly encoded vector to THIS store's live index. */
+    add(id: number, vec: Float32Array): void;
+    /**
+     * 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`. */
+    readonly writeBatch?: number;
+    /** Called once per row whose encode (or live-index add) failed. */
+    onRowError?(row: VectorEncodeRow, error: unknown): void;
+    /** Called once per group whose `write` failed, with the rows that never reached the database. */
+    onWriteError?(rows: readonly EncodedVector[], error: unknown): void;
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function encodeAndPersist(rows: readonly VectorEncodeRow[], target: EncodeWriteTarget): Promise<{
+    encoded: number;
+    failed: number;
+}>;
+/**
+ * ONE bounded slice of the repair: re-add unusable-but-readable vectors that the live index lost,
+ * drop the rows a re-encode has to replace, then encode up to `limit` missing/foreign rows.
+ *
+ * `limit` is what makes the SAME logic usable as a background migration: one call is a bounded unit
+ * of work the caller can yield between. The explicit fix passes no limit (the operator action drains
+ * everything); the background drive passes its batch size.
+ *
+ * The ORDER is an invariant: unusable bytes leave the table and the live index first, so a
+ * re-encode can pick them up and a process that dies mid-migration leaves at most one batch
+ * vector-less — exactly the `missing` rows the next run resumes on.
+ */
+export declare function repairVectorSlice(target: VectorRepairTarget, opts: {
+    dryRun: boolean;
+    limit?: number;
+}): Promise<{
+    report: VectorsFixStoreReport;
+    remaining: number;
+}>;
+/**
+ * ONE bounded slice of the background migration — the unit the drive (and the tests) step.
+ *
+ * Resumability is a property of the DATABASE, not of this process: every slice re-derives what is
+ * stale from the persisted width/space, so a restart simply continues where the last slice stopped.
+ */
+export declare function migrateVectorSlice(target: VectorRepairTarget, batchSize?: number): Promise<VectorMigrationProgress>;
+/** Options for the background drive; the four log kinds go to `log` (the host logger by default). */
+export interface DriveVectorRepairOptions {
+    batchSize?: number;
+    /** Plugin unmount / runtime shutdown: stop at the next batch boundary. */
+    shouldStop?: () => boolean;
+    onProgress?: (progress: VectorMigrationOutcome) => void;
+    /** Log sink; `retrievalLogger()` (the host logger once the runtime installed it) when omitted. */
+    log?: AvantfLogger;
+}
+/**
+ * Drive the bounded background migration for one store until it is current, the model is
+ * unavailable, or `shouldStop()` turns true (plugin unmount / process shutdown). A batch FAILURE
+ * never rejects: it is logged and reported as `remaining > 0`, which is what makes the next
+ * heartbeat a retry. Never blocks the event loop for longer than one batch.
+ *
+ * Honours `semantic.auto_migrate` (default on) — the switch exists so a host that must not spend CPU
+ * on background re-encoding can leave the loud warning and the manual entry as the only path. The
+ * switch is read through the adapter so a new store cannot forget it.
+ */
+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.
+ *
+ * `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.
+ */
+export declare function vectorsFix(targets: Partial<Record<VectorRepairStore, VectorRepairTarget>>, opts: {
+    dryRun: boolean;
+    store?: VectorRepairStore;
+}): Promise<VectorsFixReport>;

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

@@ -1,13 +1,12 @@
 import { z } from 'zod';
 /**
- * Input window of the SHIPPED models: `Xenova/bge-base-zh-v1.5` (embedder) and
- * `Xenova/bge-reranker-base` (reranker) both read 512 tokens. (The previous 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.)
+ * Input window of the SHIPPED model: `Xenova/bge-base-zh-v1.5` reads 512 tokens. (The previous
+ * 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, the
- * reranker's pair budget (retrieval-core), and `knowledge.chunk_size` below. transformers.js
- * truncates past the window SILENTLY, so every derivation has to agree on the number.
+ * 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.
  */
 export declare const DEFAULT_MODEL_WINDOW_TOKENS = 512;
 /** The merged runtime config shared by memory and knowledge stores. */
@@ -23,14 +22,6 @@ export declare const ConfigSchema: z.ZodObject<{
         auto_download: z.ZodDefault<z.ZodBoolean>;
         auto_migrate: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
-    rerank: z.ZodPrefault<z.ZodObject<{
-        backend: z.ZodDefault<z.ZodString>;
-        local_model: z.ZodDefault<z.ZodString>;
-        max_input_tokens: z.ZodDefault<z.ZodNumber>;
-        mirror: z.ZodDefault<z.ZodString>;
-        cache_dir: z.ZodDefault<z.ZodString>;
-        auto_download: z.ZodDefault<z.ZodBoolean>;
-    }, z.core.$strip>>;
     vectorStore: z.ZodPrefault<z.ZodObject<{
         backend: z.ZodDefault<z.ZodString>;
         auto_thresholds: z.ZodDefault<z.ZodObject<{
@@ -48,6 +39,7 @@ export declare const ConfigSchema: z.ZodObject<{
         min_fts_terms: z.ZodDefault<z.ZodNumber>;
         min_jaccard: z.ZodDefault<z.ZodNumber>;
         leg_cap: z.ZodDefault<z.ZodNumber>;
+        time_window: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     lifecycle: z.ZodPrefault<z.ZodObject<{
         purge_after_archived_days: z.ZodDefault<z.ZodNumber>;
@@ -120,8 +112,8 @@ export declare const KnowledgeConfigSchema: z.ZodObject<{
     chunk_size: z.ZodDefault<z.ZodNumber>;
     chunk_overlap: z.ZodDefault<z.ZodNumber>;
     source_priority: z.ZodDefault<z.ZodEnum<{
-        none: "none";
         workspace: "workspace";
+        none: "none";
     }>>;
     ingest: z.ZodPrefault<z.ZodObject<{
         local_roots: z.ZodDefault<z.ZodArray<z.ZodString>>;

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

@@ -4,7 +4,7 @@
  *
  * `@avantf/dsh-plugin-base` (the family's environment framework) installs everything it manages under a
  * single root: `$AVANTF_HOME` when set, else `~/.avantf/env`. `tools` holds external binaries
- * (pandoc), `models` the downloaded embedding/rerank weights in the flat layout the transformers.js
+ * (pandoc), `models` the downloaded embedding weights in the flat layout the transformers.js
  * cache reads. The engine's built-in defaults point HERE, not at the pre-framework
  * `~/.avantf/{tools,models}`: those legacy directories are no longer a fallback anywhere, so a
  * machine that never creates them loses nothing, and no process resolves a path that only missions

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

@@ -54,12 +54,18 @@ export declare const RememberUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     content: z.ZodString;
     category: z.ZodOptional<z.ZodString>;
     ttl_days: z.ZodOptional<z.ZodNumber>;
+    source_ref: z.ZodOptional<z.ZodString>;
+    event_date: z.ZodOptional<z.ZodString>;
+    valid_until: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"update">;
     fact_id: z.ZodNumber;
     content: z.ZodString;
     category: z.ZodOptional<z.ZodString>;
     ttl_days: z.ZodOptional<z.ZodNumber>;
+    source_ref: z.ZodOptional<z.ZodString>;
+    event_date: z.ZodOptional<z.ZodString>;
+    valid_until: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"remove">;
     fact_id: z.ZodNumber;
@@ -77,12 +83,14 @@ export declare const RecallUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     action: z.ZodLiteral<"search">;
     query: z.ZodString;
     category: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
     limit: z.ZodOptional<z.ZodNumber>;
     max_tokens: z.ZodOptional<z.ZodNumber>;
     floors: z.ZodOptional<z.ZodEnum<{
         strict: "strict";
         loose: "loose";
     }>>;
+    include_scores: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"ask">;
     subj: z.ZodOptional<z.ZodString>;
@@ -127,6 +135,7 @@ export declare const AdminUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
         active: "active";
         archived: "archived";
     }>>;
+    source: z.ZodOptional<z.ZodString>;
     limit: z.ZodOptional<z.ZodNumber>;
     offset: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
@@ -152,6 +161,10 @@ export declare const AdminUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"vectors_fix">;
     dry_run: z.ZodOptional<z.ZodBoolean>;
+    store: z.ZodOptional<z.ZodEnum<{
+        memory: "memory";
+        knowledge: "knowledge";
+    }>>;
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"contradict_check">;
 }, z.core.$strip>, z.ZodObject<{
@@ -220,6 +233,7 @@ export declare const QueryUnion: z.ZodObject<{
         strict: "strict";
         loose: "loose";
     }>>;
+    include_scores: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type QueryRequest = z.infer<typeof QueryUnion>;
 /** Transport-agnostic tool spec: name / key / description / zod input. */

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

@@ -23,7 +23,6 @@ export interface FactSummary {
     /** Remaining ACTIVE days before `forgot`; null when pinned / non-active / trust disabled. */
     remaining_days: number | null;
     helpful_count: number;
-    mirror_source: string | null;
     created_at: string;
     archived_at: string | null;
     archive_reason: string | null;
@@ -52,7 +51,6 @@ export declare const RETENTION_DIAGNOSTIC_FIELDS: readonly ["trust_score", "rema
 export declare function withoutRetentionDiagnostics<T>(value: T): T;
 export interface FactDetail extends FactSummary {
     retrieval_count: number;
-    mirror_target: string | null;
     supersedes_id: number | null;
     entities: string[];
     triples: FactTriple[];
@@ -68,6 +66,33 @@ export interface FactDetail extends FactSummary {
     /** Effective reinforcement events in the current 24h window (recall + feedback). */
     bonus_count: number;
     bonus_window_at: string | null;
+    /**
+     * P-08: where this fact came from, as recorded rows. Empty when the writer gave no `source_ref`
+     * — the read surface must show "unknown" rather than invent one.
+     */
+    sources: FactSourceView[];
+    /**
+     * P-07: when the fact became true / stopped being true. `null` = unknown; `valid_to` set while
+     * the row is still `active` means "still valid, known to end at T" (the state
+     * `mem_remember valid_until` creates), while an archived row's `valid_to` is an audit stamp.
+     */
+    valid_from: string | null;
+    valid_to: string | null;
+    /**
+     * P-07: the fact that supersedes this one, DERIVED from the existing `supersedes_id` link
+     * (reverse lookup) — no redundant column. `null` when nothing supersedes it.
+     */
+    superseded_by: number | null;
+    /**
+     * P-10: how many times this exact content has been asserted. `1` for every row that predates the
+     * counter and for a first write; a verbatim duplicate `add` moves it. Never scored.
+     */
+    assert_count: number;
+}
+/** P-08: one provenance row on a fact (`fact_sources`), as `admin detail` renders it. */
+export interface FactSourceView {
+    kind: 'session' | 'kb_doc' | 'tool' | 'manual';
+    ref: string;
 }
 /** A single hit from hybrid retrieval over the merged candidate pool. */
 export interface RecallHit {
@@ -107,6 +132,38 @@ export interface RecallHit {
      * `source_ref`, so the caller knows it exists and can fetch it explicitly.
      */
     truncated?: boolean;
+    /**
+     * P-01 per-leg evidence, present only when the caller asked (`include_scores`) — absent is the
+     * default and is what keeps the envelope byte-identical for every existing caller.
+     *
+     * Keys are the LEG NAMES actually fused for this hit's store (`semantic` / `fts` / `jaccard` /
+     * `hrr`; the HRR probe shares the jaccard weight, which is why it is named separately). A leg
+     * that did not recall this candidate is `null` — an explicit "this leg has nothing to say",
+     * which is information a missing key would lose.
+     */
+    scores?: Record<string, RecallLegScore | null>;
+    /**
+     * P-01: the FUSION output score for this hit, before any cross-store normalization.
+     *
+     * `score` is what the surface ranks by and can be re-scaled downstream (`crossQuery` min-max
+     * normalizes over the merged pool), so a caller reasoning about "which leg carried this" needs
+     * the fusion value itself rather than a number that means a different thing per surface.
+     */
+    final?: number;
+    /**
+     * P-07/P-13: the fact's event time / known end, serialized ONLY when non-null (the same
+     * convention as {@link RecallHit.truncated}). `null` means "unknown", and omitting the key keeps
+     * every pre-P-07 envelope byte-identical. Both are display/audit only — no leg filters on them.
+     */
+    valid_from?: string;
+    valid_to?: string;
+}
+/** P-01: one leg's contribution to a hit (see {@link RecallHit.scores}). */
+export interface RecallLegScore {
+    /** The leg's own raw score, on its own scale. */
+    raw: number;
+    /** `raw / legMax` in `[0,1]` — the value fusion actually weighted. Not comparable across legs. */
+    normalized: number;
 }
 /**
  * The relevance floors in force for ONE retrieval (`0` = that leg is not gated).
@@ -121,7 +178,7 @@ export interface RetrievalFloors {
     semantic: number;
     /** Distinct-query-term floor for the FTS leg (`retriever.min_fts_terms`; 1 when degraded). */
     fts: number;
-    /** Entity-overlap ratio floor (`retriever.min_jaccard`). */
+    /** Anchored query-coverage floor for the entity leg (`retriever.min_jaccard`, see `store/entity_leg.ts`). */
     jaccard: number;
 }
 /**
@@ -235,6 +292,12 @@ export interface RememberResult {
     is_new: boolean;
     revived: boolean;
     entities: string[];
+    /**
+     * P-10: how many times this content has been asserted. A first write is `1`; a verbatim
+     * duplicate `add` increments it. Reviving an archived row does NOT increment it — that is a
+     * resurrection, not a new assertion.
+     */
+    assert_count: number;
     /**
      * Contradictions detected against the existing corpus while writing this fact (DESIGN §11).
      * Present only when at least one was found, so the writer learns immediately instead of
@@ -258,11 +321,8 @@ export interface RetrievalHealth {
     /** Queries where the semantic leg was live / degraded (FTS+entity only). */
     semantic_live: number;
     semantic_degraded: number;
-    rerank_used: number;
-    rerank_fallback: number;
     /** Model-facing text that had to be bounded by a budget (see `retrieval-core/text_budget`). */
     embedding_truncated: number;
-    rerank_truncated: number;
     output_truncated: number;
     /**
      * Retrieval legs that returned exactly their cap, i.e. whose tail was dropped (`retriever.leg_cap`).
@@ -287,10 +347,7 @@ export interface RetrievalHealthSummary {
     avg_latency_ms: number;
     max_latency_ms: number;
     semantic_live_rate: number;
-    rerank_used: number;
-    rerank_fallback: number;
     embedding_truncated: number;
-    rerank_truncated: number;
     output_truncated: number;
     /** Retrieval legs that returned exactly their cap (see `RetrievalHealth`). */
     legs_capped: number;
@@ -312,6 +369,27 @@ export interface VectorSpaceHealth {
     /** Active facts whose persisted vector is provably from another model space (same width). */
     space_stale: number;
 }
+/**
+ * SQLite WAL sidecar health for the memory database (P-06).
+ *
+ * The `-wal` / `-shm` files are TRANSIENT: versioning or copying them next to `memory.db` can leave
+ * a database that will not recover. `admin stats` is offline and dependency-free by design, so it
+ * never shells out to git to ask whether they are tracked — it only reports the one fact a single
+ * `statSync` can establish. The "do not version these; `wal_checkpoint(TRUNCATE)` before a commit or
+ * a copy" rule lives in `docs/INSTALL.md`.
+ */
+export interface WalHealth {
+    /** The `-wal` sidecar exists right now (a checkpoint has not removed it, or the store is live). */
+    present: boolean;
+    /** Size of `-wal` in bytes; 0 when it does not exist or has been truncated. */
+    bytes: number;
+    /**
+     * The operator-facing reminder, non-null only while `-wal` actually holds bytes. An EMPTY
+     * sidecar (the normal post-`wal_checkpoint(TRUNCATE)` state) and an absent one are both silent —
+     * this is a backup-discipline hint, never an error.
+     */
+    warning: string | null;
+}
 /** `mem_admin stats`: store counts plus the retrieval-health counters. */
 export interface StatsSummary {
     active: number;
@@ -322,6 +400,33 @@ export interface StatsSummary {
      * status surface instead of only from a one-shot startup warning.
      */
     vectors: VectorSpaceHealth;
+    /**
+     * WAL sidecar health, so "there is an uncheckpointed `-wal` next to the database" is visible
+     * before someone versions or copies the data root.
+     */
+    wal: WalHealth;
+    /**
+     * P-08 source coverage. Reported from day one so the field cannot silently become empty: a
+     * `source_ref` that never lands (or a predicate that stops matching) shows up here as `0`.
+     */
+    sources: SourceCoverage;
+    /** P-13 `valid_from` coverage, the same "prevent an empty field" argument as {@link StatsSummary.sources}. */
+    validity: ValidityCoverage;
+}
+/** P-08: how much of the ACTIVE corpus carries provenance (`fact_sources`). */
+export interface SourceCoverage {
+    active: number;
+    /** ACTIVE facts with at least one `fact_sources` row (a fact with three sources counts once). */
+    facts_with_source: number;
+    /** `facts_with_source / active`, `0` on an empty corpus. */
+    coverage: number;
+}
+/** P-13: how much of the ACTIVE corpus carries an event time (`valid_from`). */
+export interface ValidityCoverage {
+    active: number;
+    facts_with_valid_from: number;
+    /** `facts_with_valid_from / active`, `0` on an empty corpus. */
+    coverage: number;
 }
 /** One page of facts (`mem_admin list`). */
 export interface FactPage {
@@ -402,22 +507,53 @@ export interface VectorMigrationOutcome extends VectorMigrationProgress {
     enabled: boolean;
 }
 /**
- * `mem_admin vectors_fix`: what a repair did, or — with `dry_run` — what it WOULD do.
+ * ONE store's part of a vector repair (`mem_admin vectors_fix`).
+ *
+ * The common subset (`stale` / `space_stale` / `dropped` / `encoded` / `failed` /
+ * `semantic_available`) is what both stores report; `missing` and `would_warm` are shared steps of
+ * the repair flow, and `unindexed` / `reindexed` are only meaningful to a store that tracks its live
+ * index (memory — knowledge rebuilds it at open and keeps it in sync on every write).
  *
  * `semantic_available` is "the model is loaded RIGHT NOW" (a dry run must not load it), so the
  * preview also carries `would_warm`: together they separate "unknown until you run it" from
  * "the warmup was attempted and failed".
  */
-export interface VectorsFixReport {
-    missing: number;
+export interface VectorsFixStoreReport {
+    /** ACTIVE rows whose persisted vector has the wrong width. */
     stale: number;
+    /** ACTIVE rows whose usable-width vector was recorded in another space. */
     space_stale: number;
-    unindexed: number;
-    reindexed: number;
+    /** ACTIVE rows with no persisted vector at all (what the repair has to encode). */
+    missing: number;
+    /** Rows whose unusable old-space bytes were cleared so a re-encode could replace them. */
     dropped: number;
-    fixed: number;
+    /** Rows re-encoded into the current space by this repair. */
+    encoded: number;
+    /** Rows whose encode or write failed; they stay `missing` / `stale` for the next pass. */
+    failed: number;
+    /** The model is loaded right now. */
     semantic_available: boolean;
+    /** The model was NOT loaded at entry, so a real run would attempt a warmup. */
     would_warm: boolean;
+    /** Usable persisted vectors absent from the live index (memory only). */
+    unindexed?: number;
+    /** Usable persisted vectors put back into the live index by this repair (memory only). */
+    reindexed?: number;
+}
+/**
+ * `mem_admin vectors_fix`: what a repair did, or — with `dry_run` — what it WOULD do, per store.
+ *
+ * The report is per-store because one switch and one call now cover BOTH libraries (a model swap
+ * leaves memory and knowledge in the same state, and the repair used to exist for memory only).
+ * `store` on the request narrows the call to one library; the top-level `semantic_available` is the
+ * AND over the stores actually repaired.
+ */
+export interface VectorsFixReport {
+    stores: {
+        memory?: VectorsFixStoreReport;
+        knowledge?: VectorsFixStoreReport;
+    };
+    semantic_available: boolean;
     dry_run: boolean;
 }
 /** `kb_manage ingest`: what one document produced. */