@avantf/dsh-mem 0.6.4 → 0.8.0

package/lib/engine/mem/dbdrivers/fake/surface.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The async SURFACE a mock-remote backend exposes (DB-4, docs/DB_DRIVER_LAYOUT.md §五).
+ *
+ * A `StorageBackend` is a tree of objects (`facts`, `relations.entities`, `search`, `lifecycle`, …).
+ * This module turns that tree into the same tree where every METHOD is one hop over
+ * {@link StorageTransport}: the call returns a promise, the transport may delay or fail it, and the
+ * result is the wrapped object's result unchanged.
+ *
+ * Why a proxy instead of ~90 hand-written delegating methods: the point of DB-4 is that NO method may
+ * accidentally bypass the boundary. A hand-written list can forget the method a future port adds and
+ * the suite would not notice; deriving the surface from the object means every method that exists is
+ * routed by construction. What it deliberately does NOT do: touch data properties
+ * (`migrations.from`, `migrations.applied`), arrays, or the one method the port declares synchronous
+ * ({@link AsyncSurfaceOptions.synchronous}) — those carry no I/O to simulate.
+ *
+ * @module dbdrivers/fake/surface
+ */
+import type { StorageTransport } from './transport.js';
+export interface AsyncSurfaceOptions {
+    /**
+     * Methods the PORT declares synchronous. There is exactly one today
+     * (`ContradictionRepository.configure`, which only supplies knobs); wrapping it in a promise would
+     * make the store's fire-and-forget call race the next check, so it is called through directly.
+     */
+    readonly synchronous?: readonly string[];
+}
+/**
+ * Wrap `target` so every method call is one {@link StorageTransport.request}.
+ *
+ * `label` prefixes each operation (`facts.insertRevision`), which is what makes a failure message and
+ * a test's operation log readable. Nested service objects (`relations.entities`) are wrapped lazily
+ * and cached, so the property keeps a stable identity across calls.
+ */
+export declare function asyncSurface<T extends object>(label: string, target: T, transport: StorageTransport, options?: AsyncSurfaceOptions): T;

package/lib/engine/mem/dbdrivers/fake/transport.d.ts

@@ -0,0 +1,61 @@
+/** One simulated hop. `1` is the connect (see {@link StorageTransport.connect}). */
+export interface MockRemoteTurnaround {
+    /** Simulated round-trip latency per operation, in milliseconds (default `0`). */
+    readonly latencyMs?: number;
+    /** Fail operation number `failAfter` (1-based, connect included). */
+    readonly failAfter?: number | null;
+    /** The injected failure's message; a generic one is used when absent. */
+    readonly failMessage?: string | null;
+}
+/** What one operation did — the audit trail a test asserts on ("this really went through the hop"). */
+export interface TransportRequestRecord {
+    /** 1-based order across ALL operations, the connect included. */
+    readonly sequence: number;
+    /** `facts.insertRevision`, `lifecycle.restore`, … — path + method name in the backend surface. */
+    readonly operation: string;
+    readonly latencyMs: number;
+    /** The injected failure hit this operation (the wrapped work did NOT run). */
+    failed: boolean;
+}
+/**
+ * The hop every backend call crosses. `connect()` is the open-time handshake: a remote that cannot be
+ * reached must fail `open()`, before any store exists.
+ */
+export interface StorageTransport {
+    /** A label for diagnostics (`mock-remote`). */
+    readonly kind: string;
+    connect(): Promise<void>;
+    request<T>(operation: string, work: () => T | Promise<T>): Promise<T>;
+}
+/** The error code an injected failure carries, so a caller can tell it from a driver's own failure. */
+export declare const MOCK_REMOTE_FAILURE_CODE = "MOCK_REMOTE_TRANSPORT";
+/**
+ * The in-process simulation of the hop (docs/DB_DRIVER_LAYOUT.md §五).
+ *
+ * Deterministic by default: no latency, no failure, so a suite that does not opt in behaves exactly
+ * like a local backend — which is what lets the SHARED contract run against it unchanged.
+ */
+export declare class MockRemoteTransport implements StorageTransport {
+    readonly kind = "mock-remote";
+    /** Every operation this transport served, in order (assertions and diagnostics). */
+    readonly requests: TransportRequestRecord[];
+    private sequence;
+    private pendingFailures;
+    private failMessageOverride;
+    private readonly latencyMs;
+    private readonly failAfter;
+    private readonly failMessage;
+    constructor(turnaround?: MockRemoteTurnaround);
+    /** The open-time handshake: a remote that cannot be reached fails `open()`. */
+    connect(): Promise<void>;
+    /**
+     * Fail the next `count` operations.
+     *
+     * The imperative twin of {@link MockRemoteTurnaround.failAfter}: a test that wants a SPECIFIC call
+     * to fail injects it right before that call, instead of counting every operation an implementation
+     * happens to make (a count that would break on an unrelated refactor).
+     */
+    injectFailure(count?: number, message?: string): void;
+    request<T>(operation: string, work: () => T | Promise<T>): Promise<T>;
+    private operate;
+}

package/lib/engine/mem/dbdrivers/sqlite/connection.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The SQLite driver's CONNECTION (open, PRAGMAs, WAL, busy_timeout, probe).
+ *
+ * The implementation still lives in `db/conn.ts` + `db/sqlite.ts` — `docs/DB_DRIVER_LAYOUT.md` §三
+ * allows the existing physical modules to be re-exported first and moved later. What this file fixes
+ * is the dependency direction: from here on, a driver module imports its connection from THIS module,
+ * so the physical move never touches a repository or the backend.
+ *
+ * @module dbdrivers/sqlite/connection
+ */
+export { openMemoryStore } from '../../db/conn.js';
+export type { OpenedStore, StoreSchema } from '../../db/store.js';
+export { describeSqlite, openSqlite, sqliteProbe } from '../../db/sqlite.js';
+export type { Db } from '../../db/port.js';

package/lib/engine/mem/dbdrivers/sqlite/contradictions.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The SQLite CONTRADICTION façade (log + detector).
+ *
+ * The detector itself (`lifecycle/contradiction.ts`) is domain policy; this class supplies it the
+ * connection, the configured threshold and the store's runtime knobs, and exposes the log reads the
+ * `mem_admin` surfaces use.
+ *
+ * @module dbdrivers/sqlite/contradictions
+ */
+import type { ContradictionRecord, MemoryKind } from '../../../mem-contract/index.js';
+import type { Db } from '../../db/port.js';
+import { ContradictDetector } from '../../lifecycle/contradiction.js';
+import type { EntitiesDao } from './dao/index.js';
+import type { ConflictPair, ContradictionRepository, StoredConflict } from '../../interfaces/repositories.js';
+export declare class SqliteContradictionRepository implements ContradictionRepository {
+    private readonly db;
+    private readonly entities;
+    private detector;
+    private threshold;
+    private fetchVectors;
+    constructor(db: Db, entities: EntitiesDao, threshold: number);
+    configure(options: {
+        threshold?: number;
+        fetchVectors?: (ids: number[]) => Map<number, Float32Array>;
+    }): void;
+    private get instance();
+    checkOne(factId: number): ReturnType<ContradictDetector['checkOne']>;
+    checkMany(factIds: readonly number[]): ReturnType<ContradictDetector['checkMany']>;
+    openConflictsFor(factId: number): ConflictPair[];
+    resolveForFact(factId: number): number;
+    resolveForFacts(factIds: readonly number[]): number;
+    get(id: number): StoredConflict | undefined;
+    resolve(id: number, resolution: 'true_positive' | 'false_positive', loserFactId?: number): void;
+    list(resolved?: number, kind?: MemoryKind, threshold?: number, limit?: number): ContradictionRecord[];
+}

package/lib/engine/mem/dbdrivers/sqlite/dao/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The SQLite DAOs, re-exported under the driver (docs/DB_DRIVER_LAYOUT.md §三).
+ *
+ * The DAOs are SQLite-specific by construction (FTS5, PRAGMA, `INDEXED BY`), and they physically
+ * live in `db/dao/*` today. This barrel is the only place the driver reaches for them, so the
+ * eventual physical move is a change to these export paths and nothing else — and no repository,
+ * backend or store file grows a new import of a DAO.
+ *
+ * @module dbdrivers/sqlite/dao
+ */
+export { FactsDao } from '../../../db/dao/facts.js';
+export { EntitiesDao } from '../../../db/dao/entities.js';
+export { TriplesDao } from '../../../db/dao/triples.js';
+export { StatsDao } from '../../../db/dao/stats.js';
+export { classifySourceRef, FACT_SOURCE_FALLBACK_KIND, FACT_SOURCE_KINDS, FactSourcesDao, } from '../../../db/dao/fact_sources.js';
+export type { ConflictPair, StoredConflict } from '../../../interfaces/repositories.js';

package/lib/engine/mem/dbdrivers/sqlite/driver.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The SQLite storage DRIVER (docs/DB_DRIVER_LAYOUT.md §二/§三).
+ *
+ * `sqliteDriver.open()` is the one place a SQLite backend is created: it opens (or creates) the file,
+ * applies the schema's migrations, wires the repository objects over the ONE connection and returns
+ * the portable {@link StorageBackend}. Everything above the boundary gets that object, never the
+ * `Db` — except through {@link SqliteStorageBackend.relationalHandle}, the documented transition hole
+ * for the CLI's SQL-speaking operator commands.
+ *
+ * The driver declares `contractVersion: STORAGE_CONTRACT_VERSION` and its capabilities; the registry
+ * refuses it on a host whose contract major does not match (never a silent fallback).
+ *
+ * @module dbdrivers/sqlite/driver
+ */
+import type { StorageConfig } from '../../../mem-contract/index.js';
+import type { StorageCapabilities } from '../../interfaces/capabilities.js';
+import type { MigrationRunner } from '../../interfaces/migrations.js';
+import type { ContradictionRepository, KeyValueRepository, MemoryRepository, RelationRepository, SourceRepository } from '../../interfaces/repositories.js';
+import type { SearchIndex } from '../../interfaces/search_index.js';
+import type { LifecycleService, StorageBackend } from '../../interfaces/storage_backend.js';
+import type { StorageDriver } from '../../interfaces/storage_driver.js';
+/** What this driver can do. Declared once, so the host never probes for it with a failing query. */
+export declare const SQLITE_CAPABILITIES: StorageCapabilities;
+/** The open SQLite database plus the repository objects built over its one connection. */
+export declare class SqliteStorageBackend implements StorageBackend {
+    readonly kind = "sqlite";
+    readonly capabilities: StorageCapabilities;
+    /** The facts aggregate — named `facts` per the HAL layout (`docs/DB_DRIVER_LAYOUT.md` §二). */
+    readonly facts: MemoryRepository;
+    readonly relations: RelationRepository;
+    readonly sources: SourceRepository;
+    readonly contradictions: ContradictionRepository;
+    readonly search: SearchIndex;
+    readonly keyValue: KeyValueRepository;
+    readonly lifecycle: LifecycleService;
+    readonly migrations: MigrationRunner;
+    /** The one connection. Kept private to the driver; see {@link relationalHandle}. */
+    private readonly db;
+    constructor(path: string, options?: {
+        contradictionThreshold?: number;
+    });
+    /**
+     * The driver's relational handle, for the CLI's relation-backfill commands and `AvantfRuntime.db`.
+     *
+     * These operator paths still speak SQL (`proposeRelations`, `relationBackfill`, the export
+     * reader). The STORE and every retrieval/lifecycle path go through the repositories; the type is
+     * `unknown` on the port because a portable interface cannot name `Db`, and the host casts at the
+     * one place it asks.
+     */
+    relationalHandle(): unknown;
+    close(): void;
+}
+/** The SQLite driver: the one thing `storage.driver: sqlite` selects. */
+export declare const sqliteDriver: StorageDriver<StorageConfig>;

package/lib/engine/mem/dbdrivers/sqlite/facts.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The SQLite FACTS repository (`MemoryRepository`).
+ *
+ * A thin delegation layer in front of `FactsDao`: the SQL and its plan comments stay in the DAO, so
+ * moving the driver did not change a query. What this file owns is the CONTRACT conversions:
+ * `TimeRange` (the domain's normalized window) → the DAO's bound `TimeSql`, and the DAO's
+ * `{ changes, lastInsertRowid }` → `{ inserted, factId }` (the backend assigns ids; DB-3).
+ *
+ * @module dbdrivers/sqlite/facts
+ */
+import type { MemoryKind } from '../../../mem-contract/index.js';
+import { type TimeRange } from '../../store/time_filter.js';
+import type { FactHitMeta, FactRow, FactVectorRow, FactVectorSpaceRow, HrrVectorRow, InsertRevisionOutcome, MemoryRepository } from '../../interfaces/repositories.js';
+import type { FactsDao } from './dao/index.js';
+export declare class SqliteMemoryRepository implements MemoryRepository {
+    private readonly dao;
+    constructor(dao: FactsDao);
+    activeIds(ids: readonly number[]): number[];
+    getById(factId: number): FactRow | undefined;
+    rowsByIds(ids: readonly number[]): FactRow[];
+    textsByIds(ids: readonly number[]): Map<number, string>;
+    hitMetaByIds(ids: readonly number[]): Map<number, FactHitMeta>;
+    minSettleClock(): number | null;
+    maxSettleClock(): number | null;
+    countByStatus(): {
+        active: number;
+        archived: number;
+    };
+    countActive(): number;
+    countPinnedActive(): number;
+    countInStatus(status: string, kind?: MemoryKind, source?: string): number;
+    countActiveWithValidFrom(): number;
+    countForgettingWithin(p: {
+        step: number;
+        clock: number;
+        withinDays: number;
+    }): number;
+    countIdleCandidates(days: number): number;
+    countArchiveBacklog(p: {
+        forgetThreshold: number;
+        idleCalendarDays: number;
+    }): number;
+    countPendingConflicts(): number;
+    countStaleEntities(version: number): number;
+    vectorCounts(): {
+        total: number;
+        withSemantic: number;
+        missing: number;
+    };
+    activeVectorRows(): FactVectorRow[];
+    activeVectorSpaces(): FactVectorSpaceRow[];
+    archivedByReason(): {
+        reason: string;
+        n: number;
+    }[];
+    embeddingModels(): {
+        model: string | null;
+        n: number;
+    }[];
+    assertCount(factId: number): number;
+    supersededBy(factId: number): number | null;
+    statusOf(factId: number): string | undefined;
+    bonusStatedToday(): {
+        count: number;
+        granted: number;
+    };
+    page(status: string, kind: MemoryKind | undefined, limit: number, offset: number, source?: string): FactRow[];
+    pageTimeWindow(status: string, kind: MemoryKind | undefined, time: TimeRange, limit: number, offset: number, source?: string): FactRow[];
+    countStatusTimeWindow(status: string, kind: MemoryKind | undefined, time: TimeRange, source?: string): number;
+    findByContent(content: string): FactRow | undefined;
+    windowRows(from: string, to: string, kind: MemoryKind | undefined, cap: number, source?: string): number[];
+    staleEntityRows(version: number, limit: number): {
+        fact_id: number;
+        content: string;
+        kind: string;
+    }[];
+    pendingConflictRows(limit: number, after?: number): {
+        fact_id: number;
+        content: string;
+    }[];
+    missingVectorRows(): {
+        fact_id: number;
+        content: string;
+    }[];
+    activeHrrRows(kind?: MemoryKind, limit?: number, source?: string, time?: TimeRange): HrrVectorRow[];
+    hrrRowsForFacts(ids: readonly number[], kind?: MemoryKind, source?: string): HrrVectorRow[];
+    activeIdsIn(ids: readonly number[], kind?: MemoryKind, source?: string, time?: TimeRange): number[];
+    insertRevision(v: Parameters<FactsDao['insertRevision']>[0]): InsertRevisionOutcome;
+    applyValidity(factId: number, validFrom: Parameters<FactsDao['applyValidity']>[1], validTo: Parameters<FactsDao['applyValidity']>[2]): void;
+    applyValues(factId: number, kind: MemoryKind, ttlDays: number): void;
+    setTitle(factId: number, title: string): void;
+    insertTitleAlias(factId: number, title: string): void;
+    copyTitleAliases(fromFactId: number, toFactId: number, currentTitle: string): void;
+    dropTitleAlias(factId: number, title: string): void;
+    incrementAssertCount(factId: number): number;
+    markValidTo(factId: number, at: string, atMs?: number | null): void;
+    linkSupersede(factId: number, supersedesId: number): void;
+    archiveSuperseded(factId: number, clock: number): number;
+    revive(factId: number, kind: MemoryKind, ttlDays: number, trust: number, clock: number): number;
+    archive(factId: number, clock: number, reason: string): number;
+    restore(factId: number, trust: number, clock: number): number;
+    bumpHelpful(factId: number, delta: number): void;
+    pin(factId: number, clock: number): number;
+    unpin(factId: number, clock: number): number;
+    pinOutcome(factId: number, clock: number, bonusCount: number, windowAt: string): void;
+    forgetOutcome(factId: number, trust: number, clock: number, bonusCount: number, windowAt: string): void;
+    reinforceOutcome(factId: number, trust: number, clock: number, bonusCount: number, windowAt: string): void;
+    touchUsage(ids: readonly number[]): void;
+    settleTrust(factId: number, trust: number, clock: number): void;
+    reinforce(factId: number, trust: number, clock: number, bonusCount: number, windowAt: string): void;
+    setSemanticVector(factId: number, vector: Uint8Array, model: string, store: string): void;
+    clearVectors(ids: readonly number[]): number;
+    setHrrVector(factId: number, bytes: Uint8Array): void;
+    setEntitiesVersion(ids: readonly number[], version: number): number;
+    markConflictChecked(ids: readonly number[]): number;
+    requeueConflictCheck(ids: readonly number[]): number;
+}

package/lib/engine/mem/dbdrivers/sqlite/index.d.ts

@@ -0,0 +1,6 @@
+import type { StorageBackend } from '../../interfaces/storage_backend.js';
+import { SqliteStorageBackend } from './driver.js';
+export { SqliteStorageBackend, sqliteDriver, SQLITE_CAPABILITIES } from './driver.js';
+export { describeSqlite, sqliteProbe } from './connection.js';
+/** Whether a backend was opened by THIS driver (the only driver this build ships). */
+export declare function isSqliteStorageBackend(backend: StorageBackend): backend is SqliteStorageBackend;

package/lib/engine/mem/dbdrivers/sqlite/migrations.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The SQLite driver's MIGRATION boundary (DB-3).
+ *
+ * The schema, the ordered steps and `PRAGMA user_version` handling stay in `db/conn.ts` +
+ * `db/migrations.ts` (the schema is SQLite DDL). This module turns one OPEN's result into the
+ * portable {@link MigrationRunner}: what this open applied, and a way to re-read the backend's own
+ * version without applying anything.
+ *
+ * @module dbdrivers/sqlite/migrations
+ */
+import { type MigrationResult } from '../../db/migrations.js';
+import type { Db } from '../../db/port.js';
+import type { MigrationRunner } from '../../interfaces/migrations.js';
+/** The runner for one open connection. `migration` is what the open itself reports. */
+export declare function createMigrationRunner(db: Db, migration: MigrationResult): MigrationRunner;

package/lib/engine/mem/dbdrivers/sqlite/relations.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The SQLite RELATION graph repositories (entities, triples, edges).
+ *
+ * The graph's SQL lives in `db/graph.ts` (shared with the migration/backfill code) and in
+ * `EntitiesDao`/`TriplesDao`; this file is the driver's implementation of the port shapes, including
+ * the `GraphReader` the relation planner walks (built in-memory over this connection).
+ *
+ * @module dbdrivers/sqlite/relations
+ */
+import type { MemoryKind, TimeFilter } from '../../../mem-contract/index.js';
+import type { Db } from '../../db/port.js';
+import { deleteEdgesForFact, graphCoverage, rebuildEdgesForFact, reextractEdges, writeEdgesForFact, writeExplicitEdgesForFact } from '../../db/graph.js';
+import { type TimeRange } from '../../store/time_filter.js';
+import { MemoryGraphReader } from '../../store/graph_reader.js';
+import { registerEntityAliasesFromText, type RelationCandidate } from '../../relations/index.js';
+import { explicitRelationTriples } from '../../store/explicit_relations.js';
+import type { EntitiesDao, TriplesDao } from './dao/index.js';
+import type { EntityRepository, FactContainingPage, FactsContainingAllQuery, RelationRepository, TripleRepository } from '../../interfaces/repositories.js';
+export declare class SqliteEntityRepository implements EntityRepository {
+    private readonly dao;
+    constructor(dao: EntitiesDao);
+    linkFact(factId: number, entities: Parameters<EntitiesDao['linkFact']>[1]): void;
+    unlinkFact(factId: number): void;
+    namesForFact(factId: number): string[];
+    bagsForFacts(ids: readonly number[]): Map<number, string[]>;
+    activeDocFrequency(names: readonly string[]): Map<string, number>;
+    candidateFactsForAnyEntity(names: readonly string[], kind: MemoryKind | undefined, limit: number, queryWidth: number, widthCap: number, source?: string, time?: TimeRange): number[];
+    factEntitiesIn(text: string): ReturnType<EntitiesDao['factEntitiesIn']>;
+    factsContainingAll(query: FactsContainingAllQuery): FactContainingPage;
+}
+export declare class SqliteTripleRepository implements TripleRepository {
+    private readonly dao;
+    constructor(dao: TriplesDao);
+    insertMany(factId: number, triples: Parameters<TriplesDao['insertMany']>[1]): void;
+    listForFact(factId: number): ReturnType<TriplesDao['listForFact']>;
+    deleteForFact(factId: number): void;
+}
+export declare class SqliteRelationRepository implements RelationRepository {
+    private readonly db;
+    readonly entities: EntityRepository;
+    readonly triples: TripleRepository;
+    constructor(db: Db, entities: EntitiesDao, triples: TriplesDao);
+    explicitRelationTriples(kind: MemoryKind, relations: Parameters<typeof explicitRelationTriples>[2]): RelationCandidate[];
+    registerEntityAliasesFromText(text: string, knownNames: readonly string[]): ReturnType<typeof registerEntityAliasesFromText>;
+    explicitRelationsForFact(factId: number): {
+        subject: string;
+        predicate: string;
+        object: string;
+    }[];
+    writeEdgesForFact(factId: number, triples: Parameters<typeof writeEdgesForFact>[2], options?: Parameters<typeof writeEdgesForFact>[3]): ReturnType<typeof writeEdgesForFact>;
+    writeExplicitEdgesForFact(factId: number, relations: Parameters<typeof writeExplicitEdgesForFact>[2]): ReturnType<typeof writeExplicitEdgesForFact>;
+    deleteEdgesForFact(factId: number, options?: Parameters<typeof deleteEdgesForFact>[2]): number;
+    rebuildEdgesForFact(factId: number, kind: string): ReturnType<typeof rebuildEdgesForFact>;
+    reextractEdges(options?: Parameters<typeof reextractEdges>[1]): ReturnType<typeof reextractEdges>;
+    ensureVocabulary(): void;
+    coverage(options?: Parameters<typeof graphCoverage>[1]): ReturnType<typeof graphCoverage>;
+    graphReader(filter?: {
+        kind?: MemoryKind;
+        source?: string;
+        time?: TimeFilter;
+    }): MemoryGraphReader;
+}

package/lib/engine/mem/dbdrivers/sqlite/search.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The SQLite FULL-TEXT/TITLE search index (DB-3).
+ *
+ * Everything the store is not allowed to know lives here: the FTS5 tables, their tokenizers, the
+ * `MATCH` expression builder and the short-query `LIKE` fallback. The store hands over the QUERY and
+ * receives hits whose `rank` is already normalized to "higher is better" — SQLite's `bm25` is
+ * negative, the substring predicate's term count is positive, and both leave this class in one
+ * convention so the store's floors and the fusion never branch on which path answered.
+ *
+ * The tokenizer of each table is DETECTED from the table's own DDL: `CREATE VIRTUAL TABLE IF NOT
+ * EXISTS` never rebuilds an existing table, so a database carried across SQLite builds keeps the
+ * tokenizer it was born with (see `db/tokenizer.ts`).
+ *
+ * @module dbdrivers/sqlite/search
+ */
+import type { Db } from '../../db/port.js';
+import type { FactsDao } from './dao/index.js';
+import type { ExactContentQuery, ExactTitleQuery, SearchHit, SearchIndex, SearchScope, TitleMatch, TitleQuery, TimeWindowQuery } from '../../interfaces/search_index.js';
+export declare class SqliteSearchIndex implements SearchIndex {
+    private readonly db;
+    private readonly dao;
+    private readonly contentTokenizer;
+    private readonly titleTokenizer;
+    constructor(db: Db, dao: FactsDao);
+    /**
+     * The content leg: the FTS index when the table's tokenizer can express the query, the substring
+     * fallback when the query has no term the trigram vocabulary can hold (a 2-char CJK run — see
+     * `db/tokenizer.ts#buildFtsQuery` and `store/lexical.ts#substringTerms`).
+     */
+    searchContent(query: string, scope?: SearchScope, limit?: number): SearchHit[];
+    countContentContaining(query: ExactContentQuery): number;
+    contentContainingRows(query: ExactContentQuery & {
+        limit: number;
+        offset: number;
+    }): number[];
+    countTitleEqual(query: ExactTitleQuery): number;
+    titleEqualRows(query: ExactTitleQuery & {
+        limit: number;
+        offset: number;
+    }): TitleMatch[];
+    /**
+     * The pure time window: the DAO owns both halves (the predicate AND the ORDER BY axis), so the
+     * domain `TimeRange` travels through untouched instead of being compiled here.
+     */
+    countInTimeWindow(query: TimeWindowQuery): number;
+    timeWindowRows(query: TimeWindowQuery & {
+        limit: number;
+        offset: number;
+    }): number[];
+    /**
+     * The title index, with its own fallback: an FTS5 MATCH when `titleFtsQuery` can express the
+     * query, the `title LIKE` scan otherwise (a 1–2 character keyword, or a unicode61 table).
+     */
+    searchTitles(query: TitleQuery): TitleMatch[];
+    rebuild(): void;
+}

package/lib/engine/mem/dbdrivers/sqlite/sources.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The SQLite PROVENANCE repository (`fact_sources`).
+ *
+ * `classifyRef` is pure (`kind:` prefix → kind + ref) and stays with the rows it classifies, so the
+ * classification a write performs and the rows it lands cannot drift.
+ *
+ * @module dbdrivers/sqlite/sources
+ */
+import { type FactSourcesDao } from './dao/index.js';
+import type { FactSource, FactSourceKind, SourceRepository } from '../../interfaces/repositories.js';
+export declare class SqliteSourceRepository implements SourceRepository {
+    private readonly dao;
+    constructor(dao: FactSourcesDao);
+    classifyRef(sourceRef: string): {
+        kind: FactSourceKind;
+        ref: string;
+    };
+    insert(factId: number, kind: FactSourceKind, ref: string): void;
+    listForFact(factId: number): FactSource[];
+    activeCoverage(): {
+        active: number;
+        facts_with_source: number;
+    };
+}
+/**
+ * The full-text/exact search adapter (DB-3).
+ *
+ * Everything the store is not allowed to know lives here: the FTS5 tables, their tokenizers, the
+ * `MATCH` expression builder and the short-query `LIKE` fallback. The store hands over the QUERY and
+ * receives hits whose `rank` is already normalized to "higher is better" — SQLite's `bm25` is
+ * negative, the substring predicate's term count is positive, and both leave this class in one
+ * convention so the store's floors and the fusion never branch on which path answered.
+ *
+ * The tokenizer of each table is DETECTED from the table's own DDL: `CREATE VIRTUAL TABLE IF NOT
+ * EXISTS` never rebuilds an existing table, so a database carried across SQLite builds keeps the
+ * tokenizer it was born with (see `db/tokenizer.ts`).
+ */

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

@@ -7,9 +7,8 @@
  *   - `DEFAULT_SEARCH_LIMIT` — `query`'s own input schema carries `.default(10)`
  *     (`contract/src/tools.ts`), and the recall actions' descriptions say "默认 10"; the recall union
  *     itself is `.optional()`, so the engine is what applies it. It reaches `hybridSearch` (a
- *     non-finite limit) and the cross-store router.
- *   - `DEFAULT_LIST_LIMIT` — the documented page for `admin list` and `kb_list` ("默认 50" /
- *     "缺省 50", same file).
+ *     non-finite limit).
+ *   - `DEFAULT_LIST_LIMIT` — the documented page for `admin list` ("默认 50").
  *
  * The cross-layer equation is pinned by `test/hybrid.spec.ts` against the contract's parsed schema,
  * so a contract default moving and this constant not moving is a red test rather than a silent
@@ -21,5 +20,5 @@
  */
 /** Page of a recall/query result when the caller gave no usable `limit`. */
 export declare const DEFAULT_SEARCH_LIMIT = 10;
-/** Page of a listing surface (`admin list`, `kb_list`) when the caller gave no `limit`. */
+/** Page of a listing surface (`admin list`) when the caller gave no `limit`. */
 export declare const DEFAULT_LIST_LIMIT = 50;

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

@@ -4,41 +4,16 @@
  *
  * It lives here rather than in each adapter because the key set is owned by the contract's
  * `TOOL_SPECS`, and an adapter that hand-writes its own switch rots silently when a spec is added.
- * That is a measured failure, not a hypothetical: `kb_add`/`kb_list`/`kb_remove`/`kb_reindex` were
- * advertised by the MCP server's `tools/list` while its dispatcher still knew only the five older
- * keys, so all four answered `unknown tool key` — a tool that is listed, callable, and always
- * broken. One table keyed by the contract, plus {@link supportsToolKey} so a spec test can assert
- * "every advertised key dispatches" instead of trusting a hand-maintained list.
+ * That is a measured failure, not a hypothetical: a tool advertised by one surface's tool list while
+ * its dispatcher knew only the older keys answers `unknown tool key` — a tool that is listed,
+ * callable, and always broken. One table keyed by the contract, plus {@link supportsToolKey} so a
+ * spec test can assert "every advertised key dispatches" instead of trusting a hand-maintained list.
  *
  * `ToolSpec.key` is typed `string` (not a literal union), so exhaustiveness cannot be checked at
  * compile time — the spec assertion is the gate.
  */
-import type { KbAddRequest, ToolEnvelope, ToolSpec } from '../mem-contract/index.js';
-import type { AvantfRuntime } from './runtime.js';
-/**
- * The default page for a model-facing `kb_list` — the SAME page the operator's `admin list` uses.
- *
- * Without one, `kb_list` on a large library read and parsed EVERY managed file (resolving a path
- * needs the file's frontmatter to detect collisions) to answer a question nobody asked in full. The
- * two surfaces were separate literals; the contract documents both as 50, so they are one constant
- * (`src/defaults.ts`).
- */
-export declare const KB_LIST_DEFAULT_LIMIT = 50;
-/**
- * The `kb_add` handler: a thin shell over the runtime's ADD-ONLY face (`rt.kbAdd`), which shares the
- * store's plan/classify/dispatch entry with the UI's 入库 (`rt.kb`) and differs only in the mode.
- *
- * This is the fix for a measured failure: told to "update the KB", a model called the old all-in-one
- * tool with a *new* title, which silently created a sibling document (《… · 补遗》) while the
- * original stayed behind — two overlapping documents, and the reader left to reconcile them.
- * Replacing is now an explicit file edit.
- *
- * The refusal itself lives in the STORE (the plan stage), not here: a pre-check in this handler used
- * to derive the title as `req.title ?? req.source`, which is exactly the fallback the store no
- * longer uses — so once the store derives an untitled paste from its body, a local pre-check would
- * check a different identity than the one the store actually writes.
- */
-export declare function kbAdd(rt: AvantfRuntime, data: KbAddRequest): Promise<unknown>;
+import type { ToolEnvelope, ToolSpec } from '../mem-contract/index.js';
+import type { AvantfRuntime, RememberWriteRules } from './runtime.js';
 /** Whether {@link dispatchToolKey} can answer this contract tool key. */
 export declare function supportsToolKey(key: string): boolean;
 /**
@@ -50,7 +25,7 @@ export declare function supportsToolKey(key: string): boolean;
  * rather than returning a payload, so a surface cannot mistake it for a successful empty result —
  * both adapters route the throw through their structured error envelope.
  */
-export declare function dispatchToolKey(rt: AvantfRuntime, key: string, args: Record<string, unknown>): Promise<unknown>;
+export declare function dispatchToolKey(rt: AvantfRuntime, key: string, args: Record<string, unknown>, rules?: RememberWriteRules): Promise<unknown>;
 /**
  * The ONE model-facing boundary: validate against the contract spec, dispatch the key, and shape the
  * result into the agent envelope.