@avantf/dsh-mem 0.6.4 → 0.8.0

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

@@ -0,0 +1,472 @@
+/**
+ * The storage boundary (DB-1, docs/DATABASE_PORTABILITY.md §四/§十二; async from DB-2).
+ *
+ * `MemoryStore` and the lifecycle code above it talk to these interfaces, never to a DAO, a
+ * `Db`, SQL, FTS5 or a driver. The only implementation is the SQLite adapter
+ * (`storage/sqlite.ts`), which wraps the existing DAOs; selecting it is the composition root's job
+ * (`storage/index.ts#createStorageBackend`).
+ *
+ * ASYNC BOUNDARY (DB-2). Every method that touches stored state returns {@link Awaitable}: the
+ * in-process SQLite adapter fulfils the contract by returning a plain value (it has no I/O to wait
+ * for), while a remote backend returns a promise. Callers ALWAYS `await`, so the store never has to
+ * know which kind of backend it holds, and no call site has to be rewritten again when a remote
+ * backend arrives. The lifetime of the boundary is the point: `Awaitable` is not a convenience for
+ * the local adapter, it is what makes the local adapter a legal implementation of a remote contract.
+ *
+ * WHAT DOES NOT CROSS THIS BOUNDARY: SQL text, `Db`, `DbStatement`, `TimeSql`, driver row classes,
+ * FTS5 query syntax, `bm25`'s sign convention, SQLite rowids or `AUTOINCREMENT` assumptions. Rows and
+ * result objects are the domain shapes the store already consumes; ranks are normalized to "higher is
+ * better" by the adapter that knows its own index; fact ids are handed back as ids, not rowids.
+ *
+ * @module storage/ports
+ */
+import type { ContradictionRecord, FactSourceView, MemoryKind, RelationInput } from '../../mem-contract/index.js';
+import type { GraphReader } from '../../graph-recall/index.js';
+import type { RelationVocabulary } from '../store/relation_planner.js';
+import type { ExtractedEntity } from '../entities/extract.js';
+import type { TimeRange } from '../store/time_filter.js';
+import type { EdgeReextractOptions, EdgeReextractReport, EdgeRebuildReport, EdgeSourceTriple, EdgeWriteReport, GraphCoverageReport } from '../db/graph.js';
+import type { CheckResult } from '../lifecycle/contradiction.js';
+import type { ConflictPair, StoredConflict } from '../db/dao/contradictions.js';
+import type { MaintenanceResult } from '../lifecycle/maintenance.js';
+import type { TickResult } from '../lifecycle/tick.js';
+import type { FactsExportDocument } from '../facts_io.js';
+import type { RestoreOptions, RestoreReport } from '../store/facts_restore.js';
+import type { RelationCandidate } from '../relations/index.js';
+import type { AliasRegistration } from '../relations/normalize.js';
+/**
+ * A result the in-process adapter can produce synchronously and a remote adapter returns as a
+ * promise. Callers always `await`; see the module comment for why this is not a local shortcut.
+ */
+export type Awaitable<T> = T | Promise<T>;
+/** A facts row as the domain reads it. The SQL projection lives in the adapter. */
+export type FactRow = Record<string, unknown>;
+/** One fact's source provenance (P-08). */
+export type FactSourceKind = FactSourceView['kind'];
+export interface FactSource {
+    kind: FactSourceKind;
+    ref: string;
+}
+/** The scalar display columns of a hit (`factHits` maps these onto the contract envelope). */
+export interface FactHitMeta {
+    created_at: string;
+    updated_at: string | null;
+    valid_from: string | null;
+    valid_to: string | null;
+    title: string | null;
+}
+/** One persisted semantic vector, as the reload/repair flows read it. */
+export interface FactVectorRow {
+    fact_id: number;
+    semantic_vector: Uint8Array;
+    embedding_model: string | null;
+}
+/** The space-qualified vector inventory (`facts_wide` diagnostic). */
+export interface FactVectorSpaceRow {
+    fact_id: number;
+    bytes: number;
+    embedding_model: string | null;
+}
+/** One persisted HRR bundle. */
+export interface HrrVectorRow {
+    fact_id: number;
+    hrr_vector: Uint8Array;
+}
+/** One title-search row (`mem_recall.titles`). */
+export interface TitleMatch {
+    fact_id: number;
+    title: string;
+    kind: string;
+    status: string;
+    created_at: string | null;
+    updated_at: string | null;
+    valid_from: string | null;
+    excerpt: string | null;
+}
+/** The filters every title statement applies. */
+export interface TitleFilters {
+    kind?: MemoryKind;
+    status: 'active' | 'archived' | 'all';
+    time?: TimeRange;
+}
+/**
+ * One title search. The QUERY is the domain input: whether it is answered by a full-text index or by
+ * a substring scan is the adapter's decision (DB-3), exactly like the content search below.
+ */
+export interface TitleQuery extends TitleFilters {
+    query: string;
+    limit: number;
+}
+export interface ExactTitleQuery extends TitleFilters {
+    query: string;
+}
+/** The exact-content filter (docs/RECALL_INTERFACE.md §2.2). */
+export interface ExactContentQuery {
+    query: string;
+    kind?: MemoryKind;
+    source?: string;
+    time?: TimeRange;
+}
+/**
+ * A full-text hit: the fact id and the backend's own relevance rank.
+ *
+ * HIGHER IS ALWAYS BETTER. The adapter normalizes its index's convention (SQLite's `bm25` is
+ * negative; the substring predicate's match count is positive) so the store's floors and the fusion
+ * see one scale no matter which index answered (DB-3).
+ */
+export interface SearchHit {
+    id: number;
+    rank: number;
+}
+/** The filters shared by the lexical legs. */
+export interface SearchScope {
+    kind?: MemoryKind;
+    source?: string;
+    time?: TimeRange;
+}
+/**
+ * What one insert-or-ignore did.
+ *
+ * `inserted: false` means the content already exists and the backend resolved the write onto the
+ * EXISTING row; `factId` names that row. Ids are the backend's to assign (a distributed backend does
+ * not have SQLite's rowids), which is why the store never reads a driver's `lastInsertRowid`.
+ */
+export interface InsertRevisionOutcome {
+    inserted: boolean;
+    factId: number;
+}
+/**
+ * The facts aggregate: reads, lifecycle writes and the derived-state stamps.
+ *
+ * Method names mirror the existing DAO because DB-1 was a boundary extraction, not a redesign of
+ * what the store asks for. The arguments/results are domain shapes — `TimeRange` instead of a SQL
+ * fragment, `FactRow` instead of a driver statement.
+ */
+export interface MemoryRepository {
+    activeIds(ids: readonly number[]): Awaitable<number[]>;
+    getById(factId: number): Awaitable<FactRow | undefined>;
+    rowsByIds(ids: readonly number[]): Awaitable<FactRow[]>;
+    textsByIds(ids: readonly number[]): Awaitable<Map<number, string>>;
+    hitMetaByIds(ids: readonly number[]): Awaitable<Map<number, FactHitMeta>>;
+    minSettleClock(): Awaitable<number | null>;
+    maxSettleClock(): Awaitable<number | null>;
+    countByStatus(): Awaitable<{
+        active: number;
+        archived: number;
+    }>;
+    countActive(): Awaitable<number>;
+    countPinnedActive(): Awaitable<number>;
+    countInStatus(status: string, kind?: MemoryKind, source?: string): Awaitable<number>;
+    countActiveWithValidFrom(): Awaitable<number>;
+    countForgettingWithin(p: {
+        step: number;
+        clock: number;
+        withinDays: number;
+    }): Awaitable<number>;
+    countIdleCandidates(days: number): Awaitable<number>;
+    countArchiveBacklog(p: {
+        forgetThreshold: number;
+        idleCalendarDays: number;
+    }): Awaitable<number>;
+    countPendingConflicts(): Awaitable<number>;
+    countStaleEntities(version: number): Awaitable<number>;
+    vectorCounts(): Awaitable<{
+        total: number;
+        withSemantic: number;
+        missing: number;
+    }>;
+    activeVectorRows(): Awaitable<FactVectorRow[]>;
+    activeVectorSpaces(): Awaitable<FactVectorSpaceRow[]>;
+    archivedByReason(): Awaitable<{
+        reason: string;
+        n: number;
+    }[]>;
+    embeddingModels(): Awaitable<{
+        model: string | null;
+        n: number;
+    }[]>;
+    assertCount(factId: number): Awaitable<number>;
+    supersededBy(factId: number): Awaitable<number | null>;
+    statusOf(factId: number): Awaitable<string | undefined>;
+    bonusStatedToday(): Awaitable<{
+        count: number;
+        granted: number;
+    }>;
+    page(status: string, kind: MemoryKind | undefined, limit: number, offset: number, source?: string): Awaitable<FactRow[]>;
+    findByContent(content: string): Awaitable<FactRow | undefined>;
+    windowRows(from: string, to: string, kind: MemoryKind | undefined, cap: number, source?: string): Awaitable<number[]>;
+    staleEntityRows(version: number, limit: number): Awaitable<{
+        fact_id: number;
+        content: string;
+        kind: string;
+    }[]>;
+    pendingConflictRows(limit: number, after?: number): Awaitable<{
+        fact_id: number;
+        content: string;
+    }[]>;
+    missingVectorRows(): Awaitable<{
+        fact_id: number;
+        content: string;
+    }[]>;
+    activeHrrRows(kind?: MemoryKind, limit?: number, source?: string, time?: TimeRange): Awaitable<HrrVectorRow[]>;
+    hrrRowsForFacts(ids: readonly number[], kind?: MemoryKind, source?: string): Awaitable<HrrVectorRow[]>;
+    activeIdsIn(ids: readonly number[], kind?: MemoryKind, source?: string, time?: TimeRange): Awaitable<number[]>;
+    insertRevision(v: {
+        content: string;
+        kind: MemoryKind;
+        ttlDays: number;
+        supersedesId: number | null;
+        hrr: Uint8Array;
+        trust: number;
+        clock: number;
+        pinned: 0 | 1;
+        pinnedAt: string | null;
+        windowAt: string;
+        createdAt: string;
+        title?: string | null;
+        validFrom?: string | null;
+        validTo?: string | null;
+        validFromMs?: number | null;
+        validToMs?: number | null;
+    }): Awaitable<InsertRevisionOutcome>;
+    applyValidity(factId: number, validFrom: {
+        text: string;
+        ms: number;
+    } | undefined, validTo: {
+        text: string;
+        ms: number;
+    } | undefined): Awaitable<void>;
+    applyValues(factId: number, kind: MemoryKind, ttlDays: number): Awaitable<void>;
+    setTitle(factId: number, title: string): Awaitable<void>;
+    incrementAssertCount(factId: number): Awaitable<number>;
+    markValidTo(factId: number, at: string, atMs?: number | null): Awaitable<void>;
+    linkSupersede(factId: number, supersedesId: number): Awaitable<void>;
+    archiveSuperseded(factId: number, clock: number): Awaitable<number>;
+    revive(factId: number, kind: MemoryKind, ttlDays: number, trust: number, clock: number): Awaitable<number>;
+    archive(factId: number, clock: number, reason: string): Awaitable<number>;
+    restore(factId: number, trust: number, clock: number): Awaitable<number>;
+    bumpHelpful(factId: number, delta: number): Awaitable<void>;
+    pin(factId: number, clock: number): Awaitable<number>;
+    unpin(factId: number, clock: number): Awaitable<number>;
+    pinOutcome(factId: number, clock: number, bonusCount: number, windowAt: string): Awaitable<void>;
+    forgetOutcome(factId: number, trust: number, clock: number, bonusCount: number, windowAt: string): Awaitable<void>;
+    reinforceOutcome(factId: number, trust: number, clock: number, bonusCount: number, windowAt: string): Awaitable<void>;
+    touchUsage(ids: readonly number[]): Awaitable<void>;
+    settleTrust(factId: number, trust: number, clock: number): Awaitable<void>;
+    reinforce(factId: number, trust: number, clock: number, bonusCount: number, windowAt: string): Awaitable<void>;
+    setSemanticVector(factId: number, vector: Uint8Array, model: string, store: string): Awaitable<void>;
+    clearVectors(ids: readonly number[]): Awaitable<number>;
+    setHrrVector(factId: number, bytes: Uint8Array): Awaitable<void>;
+    setEntitiesVersion(ids: readonly number[], version: number): Awaitable<number>;
+    markConflictChecked(ids: readonly number[]): Awaitable<number>;
+    requeueConflictCheck(ids: readonly number[]): Awaitable<number>;
+}
+/** Entity writes/reads used by the write path, the entity leg and the contradiction detector. */
+export interface EntityRepository {
+    linkFact(factId: number, entities: readonly ExtractedEntity[]): Awaitable<void>;
+    unlinkFact(factId: number): Awaitable<void>;
+    namesForFact(factId: number): Awaitable<string[]>;
+    bagsForFacts(ids: readonly number[]): Awaitable<Map<number, string[]>>;
+    activeDocFrequency(names: readonly string[]): Awaitable<Map<string, number>>;
+    candidateFactsForAnyEntity(names: readonly string[], kind: MemoryKind | undefined, limit: number, queryWidth: number, widthCap: number, source?: string, time?: TimeRange): Awaitable<number[]>;
+}
+/** One stored triple row (detail view). */
+export interface StoredTriple {
+    subj: string;
+    pred: string;
+    obj: string;
+    confidence: number;
+}
+/** One triple as the extractor/producer writes it. */
+export interface TripleInput {
+    subj: string;
+    pred: string;
+    obj: string;
+    confidence: number;
+    source: string;
+}
+export interface TripleRepository {
+    insertMany(factId: number, triples: readonly TripleInput[]): Awaitable<void>;
+    listForFact(factId: number): Awaitable<StoredTriple[]>;
+    deleteForFact(factId: number): Awaitable<void>;
+}
+/**
+ * The relation graph: caller-stated/explicit edges, the versioned extractor's derived edges and the
+ * read-only walkers. The SQL stays in `db/graph.ts`; this port carries the domain shapes.
+ */
+export interface RelationRepository {
+    readonly entities: EntityRepository;
+    readonly triples: TripleRepository;
+    explicitRelationTriples(kind: MemoryKind, relations: readonly RelationInput[] | undefined): Awaitable<RelationCandidate[]>;
+    registerEntityAliasesFromText(text: string, knownNames: readonly string[]): Awaitable<AliasRegistration[]>;
+    explicitRelationsForFact(factId: number): Awaitable<{
+        subject: string;
+        predicate: string;
+        object: string;
+    }[]>;
+    writeEdgesForFact(factId: number, triples: readonly EdgeSourceTriple[], options?: {
+        dryRun?: boolean;
+        samples?: number;
+    }): Awaitable<EdgeWriteReport>;
+    writeExplicitEdgesForFact(factId: number, relations: readonly {
+        subject: string;
+        predicate: string;
+        object: string;
+    }[]): Awaitable<EdgeWriteReport>;
+    deleteEdgesForFact(factId: number, options?: {
+        keepExplicit?: boolean;
+        onlyExplicit?: boolean;
+    }): Awaitable<number>;
+    rebuildEdgesForFact(factId: number, kind: string): Awaitable<EdgeRebuildReport>;
+    reextractEdges(options?: EdgeReextractOptions): Awaitable<EdgeReextractReport>;
+    ensureVocabulary(): Awaitable<void>;
+    coverage(options?: {
+        samples?: number;
+        sampleFacts?: number;
+    }): Awaitable<GraphCoverageReport>;
+    /**
+     * The read-only walker. SYNCHRONOUS ON PURPOSE: `GraphReader` is the `@avantf/graph-recall`
+     * interface the relation planner and the UI call algorithmically (hundreds of `neighborsOf` hops
+     * per query), and it is a pure in-memory view over the rows the adapter loaded when it was built.
+     * A remote backend fills that view asynchronously in `graphReader()` itself; the walk never
+     * crosses the boundary.
+     */
+    graphReader(filter?: {
+        kind?: MemoryKind;
+        source?: string;
+        time?: import('../../mem-contract/index.js').TimeFilter;
+    }): Awaitable<GraphReader & RelationVocabulary>;
+}
+/** `fact_sources` — where a fact came from. */
+export interface SourceRepository {
+    /** The `kind:` prefix rule, kept beside the rows it writes (pure; no SQL). */
+    classifyRef(sourceRef: string): Awaitable<{
+        kind: FactSourceKind;
+        ref: string;
+    }>;
+    insert(factId: number, kind: FactSourceKind, ref: string): Awaitable<void>;
+    listForFact(factId: number): Awaitable<FactSource[]>;
+    activeCoverage(): Awaitable<{
+        active: number;
+        facts_with_source: number;
+    }>;
+}
+/** The contradiction log + detector façade. */
+export interface ContradictionRepository {
+    /**
+     * Supply the store's runtime knobs (the live vector index the embedding leg reads, plus the
+     * configured threshold). The detector is built lazily from these, so a direct store built on a
+     * backend cannot silently run with the schema default threshold.
+     */
+    configure(options: {
+        threshold?: number;
+        fetchVectors?: (ids: number[]) => Map<number, Float32Array>;
+    }): void;
+    checkOne(factId: number): Awaitable<CheckResult>;
+    checkMany(factIds: readonly number[]): Awaitable<CheckResult>;
+    openConflictsFor(factId: number): Awaitable<ConflictPair[]>;
+    resolveForFact(factId: number): Awaitable<number>;
+    resolveForFacts(factIds: readonly number[]): Awaitable<number>;
+    get(id: number): Awaitable<StoredConflict | undefined>;
+    resolve(id: number, resolution: 'true_positive' | 'false_positive', loserFactId?: number): Awaitable<void>;
+    list(resolved?: number, kind?: MemoryKind, threshold?: number, limit?: number): Awaitable<ContradictionRecord[]>;
+}
+/**
+ * Full-text / exact search (DB-3).
+ *
+ * The interface takes the CALLER'S QUERY, never a query-expression in the backend's syntax: the
+ * adapter owns its tokenizer, its full-text dialect and its rank sign. That is what lets a second
+ * backend answer the same contract with `tsvector`/`pg_trgm` without the store knowing, and it is why
+ * `searchContent` may internally fall back from its index to a substring scan (the short-query shape)
+ * without the caller branching on which path ran.
+ *
+ * The index is maintained by the backend itself (SQLite: FTS triggers); `rebuild` is the repair path
+ * a caller may run when the derived index must be re-derived from the source rows.
+ */
+export interface SearchIndex {
+    /** Ranked content search. `rank` is normalized so HIGHER IS ALWAYS BETTER. */
+    searchContent(query: string, scope?: SearchScope, limit?: number): Awaitable<SearchHit[]>;
+    countContentContaining(query: ExactContentQuery): Awaitable<number>;
+    contentContainingRows(query: ExactContentQuery & {
+        limit: number;
+        offset: number;
+    }): Awaitable<number[]>;
+    countTitleEqual(query: ExactTitleQuery): Awaitable<number>;
+    titleEqualRows(query: ExactTitleQuery & {
+        limit: number;
+        offset: number;
+    }): Awaitable<TitleMatch[]>;
+    /** Title search: title-equal, else the adapter's own title index / substring fallback. */
+    searchTitles(query: TitleQuery): Awaitable<TitleMatch[]>;
+    /** Clear and re-derive the index from the source rows. */
+    rebuild(): Awaitable<void>;
+}
+/** The `avantf_stats` key/value side table (retrieval health; the lifecycle clock stays internal). */
+export interface KeyValueRepository {
+    read(key: string): Awaitable<string | null>;
+    write(key: string, value: string): Awaitable<void>;
+}
+/**
+ * The backend's connection-scoped services: transactions, the lifecycle pass, the active-day clock
+ * and the restore transaction.
+ *
+ * TRANSACTIONS ARE ASYNC (DB-2). `work` may `await` repository calls — a remote backend has no other
+ * option, and the store's write paths are one unit of work whichever backend runs them. The callback
+ * form is deliberate: no backend can hand out a live transaction object that survives an `await`
+ * without leaking its dialect (docs/DATABASE_PORTABILITY.md §四).
+ */
+export interface LifecycleService {
+    transaction<T>(work: () => T | Promise<T>): Promise<T>;
+    immediateTransaction<T>(work: () => T | Promise<T>): Promise<T>;
+    optimize(): Awaitable<void>;
+    initClock(): Awaitable<void>;
+    clock(): Awaitable<number>;
+    advancePresence(opts?: {
+        nowMs?: number;
+        gapCapDays?: number;
+    }): Awaitable<{
+        clock: number;
+        counted: number;
+    }>;
+    trustTick(config: import('../../mem-contract/index.js').Config, opts: {
+        clock: number;
+        budget?: number | null;
+    }): Awaitable<TickResult>;
+    maintenance(config: import('../../mem-contract/index.js').Config, opts?: {
+        clock?: number;
+        budget?: number | null;
+    }): Awaitable<MaintenanceResult>;
+    restore(doc: FactsExportDocument, reindexEntities: (budget?: number) => Promise<import('../store/entity_sweep.js').EntitySweepReport>, options?: RestoreOptions): Promise<RestoreReport>;
+}
+/**
+ * What one open applied (`PRAGMA user_version` on SQLite), exposed for the startup log and the tests.
+ *
+ * A backend keeps its own schema/migration state (a table, a version row, a service endpoint);
+ * `current` is how a caller re-reads it without applying anything — the hook DB-4's migration/import
+ * tooling needs, and the one thing the open-time summary cannot answer.
+ */
+export interface MigrationRunner {
+    readonly from: number;
+    readonly to: number;
+    readonly applied: readonly number[];
+    current(): Awaitable<number>;
+}
+/**
+ * The composition-root result. `MemoryStore` receives this object, not a `Db`.
+ *
+ * `vectors` is deliberately absent: the vector index is a retrieval dependency resolved by the
+ * runtime (`resolveVStore`) before the store is built, and the storage boundary only owns the
+ * `facts` table's persisted blobs (docs/DATABASE_PORTABILITY.md §十二.2).
+ */
+export interface StorageBackend {
+    readonly kind: string;
+    readonly memory: MemoryRepository;
+    readonly relations: RelationRepository;
+    readonly sources: SourceRepository;
+    readonly contradictions: ContradictionRepository;
+    readonly search: SearchIndex;
+    readonly keyValue: KeyValueRepository;
+    readonly lifecycle: LifecycleService;
+    readonly migrations: MigrationRunner;
+    close(): void | Promise<void>;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * The storage driver REGISTRY (docs/DB_DRIVER_LAYOUT.md §一/§八).
+ *
+ * `storage/` does nothing but select and hold drivers: no SQL, no repository, no dialect. A driver
+ * registers itself by importing the driver package (`dbdrivers/sqlite/index.ts` does so for the
+ * builtin), and the host resolves the configured name here.
+ *
+ * REGISTRATION VALIDATES THE CONTRACT MAJOR. A driver written against an incompatible interface is
+ * refused with {@link UnsupportedStorageContractError} at registration time — before any file is
+ * opened and before anything can half-work. There is no fallback to another driver.
+ *
+ * @module storage/registry
+ */
+import type { StorageDriver } from '../interfaces/storage_driver.js';
+import { UnsupportedStorageContractError } from '../interfaces/version.js';
+/** Raised when a driver declares a contract major this host does not implement. Re-exported there. */
+export { UnsupportedStorageContractError };
+/**
+ * Register a driver under its `name`.
+ *
+ * @throws {UnsupportedStorageContractError} when `driver.contractVersion` is not a supported major.
+ * @throws {Error} when the name is already registered by a DIFFERENT driver object (a colliding
+ *   external package must be an explicit choice, not a load-order accident).
+ */
+export declare function registerStorageDriver<Config>(driver: StorageDriver<Config>): void;
+/** The driver registered under `name`, or `undefined`. */
+export declare function lookupStorageDriver(name: string): StorageDriver<never> | undefined;
+/** The names this host can open (for an error message or a startup log). */
+export declare function storageDriverNames(): string[];
+/**
+ * Whether this host can open `driver`: the OPEN-time half of the contract check.
+ *
+ * Registration already refuses a mismatched driver, but a driver object can also arrive from
+ * `createStorageBackend`'s caller (a test harness, an embedder). Open re-checks rather than trusting
+ * the registry, and refuses the same way — never a fallback.
+ */
+export declare function assertSupportedDriver(driver: Pick<StorageDriver, 'name' | 'contractVersion'>): void;

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

@@ -0,0 +1,28 @@
+import { type Db } from '../db/conn.js';
+import type { ContradictionRepository, KeyValueRepository, LifecycleService, MemoryRepository, MigrationRunner, RelationRepository, SearchIndex, SourceRepository, StorageBackend } from './ports.js';
+/** The open SQLite database plus the adapter objects built over its one connection. */
+export declare class SqliteStorageBackend implements StorageBackend {
+    readonly kind = "sqlite";
+    readonly memory: 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 adapter; runtime-owned consumers use `leaseHandle`. */
+    private readonly db;
+    constructor(path: string, options?: {
+        contradictionThreshold?: number;
+    });
+    /**
+     * The runtime's transitional handle, for the CLI's relation-backfill commands and `AvantfRuntime.db`.
+     *
+     * DB-1's boundary is about the store and the DAOs it constructs; `Db` remains the relational port
+     * (not a driver), and two CLI commands still use it directly. DB-2 removes this lease once those
+     * commands go through a repository method.
+     */
+    leaseHandle(): Db;
+    close(): void;
+}

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

@@ -18,7 +18,7 @@ import type { SemanticBackend, VectorStore } from '../../mem-retrieval/index.js'
  * `@avantf/mem-contract`'s `toWellFormedText` is the implementation (well-formed + NFC); this name
  * is the store-layer entry, so the write paths say WHAT they are doing ("normalize this for a
  * write") rather than repeating a Unicode recipe. Every text field a store persists — fact content,
- * category, archive reason, a document's domain/source/title/uri, entity names and the SPO slots of
+ * archive reason, a document's domain/source/title/uri, entity names and the SPO slots of
  * extracted triples — goes through here, which is what keeps a lone surrogate (and the strict-JSON
  * failure it causes downstream) out of the database in the first place.
  */

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

@@ -37,6 +37,16 @@
  * (silent beats noisy), and the FTS leg's 2-char substring fallback (§20.20⑦) serves the 2-char
  * shape.
  *
+ * WHY THE FLOOR IS NOT THE WHOLE BAR (2026-10-21). `min_jaccard` was calibrated on the OLD Jaccard
+ * unit, but the metric above has a different one: a maximally wide fact sharing ONE anchor scores
+ * `1/(W + cap)` — `0.25` for `W=1`, which clears a `0.2` floor for free. The floor alone therefore
+ * cannot tell "one generic anchor" from "one rare anchor", and the anchor filter only removes words
+ * ABOVE the ceiling; anchors just inside it kept dragging wide facts in. Each candidate now also
+ * clears {@link entityEvidenceFloor}, a bar expressed in the SAME unit and weighted by the shared
+ * anchors' {@link anchorCommonness}: a unique anchor leaves `min_jaccard` in charge (the rare-name
+ * reachability this metric exists for), an anchor at the ceiling costs two anchors. `min_jaccard`
+ * stays the operator's lower bound and the reported `floors.jaccard`.
+ *
  * WHAT `W` COUNTS, AND WHY IT IS NOT `|A|`. `W` is the query's FULL entity count — every entity the
  * extractor returned, generic or absent included. A Jaccard denominator is the union of what the
  * query asked for, and the old metric counted all of it; keeping `W` there is what makes a narrow
@@ -53,8 +63,18 @@
  *
  * @module store/entity_leg
  */
-/** An entity is an anchor at or below `max(ANCHOR_MIN, ceil(ANCHOR_RATE × activeFacts))`. */
-export declare const ANCHOR_RATE = 0.2;
+/**
+ * An entity is an anchor at or below `max(ANCHOR_MIN, ceil(ANCHOR_RATE × activeFacts))`.
+ *
+ * 0.1, not 0.2 (2026-10-21). Measured on the live store: 165 active facts ⇒ the 0.2 ceiling was 33,
+ * and `用户` sat at df **32** — one fact inside the line — so every fact mentioning it became an
+ * entity-leg candidate at `1/(1+3) = 0.25` (>= the 0.2 floor) with no semantic and no FTS support:
+ * 7 of the 10 hits for 「我是谁？」 were that tail (`final` 0.1125). At 0.1 the ceiling is 17 and the
+ * word is correctly generic. The frozen eval (`eval_zh`, 41 queries + the self-query sentinel) is
+ * bit-identical under either rate — its fixtures are small enough that `ANCHOR_MIN` dominates — so
+ * this narrows noise on a real corpus without moving the measured quality numbers.
+ */
+export declare const ANCHOR_RATE = 0.1;
 /**
  * Small-corpus forgiveness, and its bound.
  *
@@ -84,6 +104,43 @@ export declare function anchorCeiling(corpus: number): number;
  * set, and a stable order keeps the SQL/scoring deterministic).
  */
 export declare function selectAnchors(queryEntities: Iterable<string>, df: ReadonlyMap<string, number>, corpus: number): string[];
+/**
+ * How many anchors the bar demands at the TOP of the anchor band, expressed in the metric's own
+ * unit: `2` = the score of a maximally wide fact that shares TWO anchors. This is the constant that
+ * ties the threshold to the metric instead of to a second, unrelated number (see
+ * {@link entityEvidenceFloor}).
+ */
+export declare const ENTITY_RARITY_SPAN = 2;
+/**
+ * An anchor's position in the anchor band, in `[0, 1]`: `0` = unique, `1` = at the ceiling.
+ *
+ * This is the IDF term of the bar, normalized against {@link anchorCeiling} rather than against the
+ * corpus size. The ceiling already IS this engine's "generic" line — `selectAnchors` drops anything
+ * above it — so normalizing by it puts the 1-anchor/2-anchor boundary at the metric's own midpoint
+ * (`commonness = 0.5` ⇒ the bar equals `1/(W + cap)`, the score of a maximally wide 1-anchor fact).
+ */
+export declare function anchorCommonness(df: number, ceiling: number): number;
+/**
+ * The LEAST rare shared anchor governs the bar: evidence is only as strong as its most generic
+ * anchor. Returns `0` when the candidate shares none (it is not entity evidence at all).
+ */
+export declare function evidenceCommonness(anchors: readonly string[], factEntities: ReadonlySet<string>, df: ReadonlyMap<string, number>, ceiling: number): number;
+/**
+ * The entity leg's evidence bar for one candidate, in the SAME unit as
+ * {@link anchoredOverlap}: `max(min_jaccard, ENTITY_RARITY_SPAN × commonness / (W + cap))`.
+ *
+ * WHY THIS SHAPE. `1/(W+cap)` is the score a maximally wide fact gets when it shares ONE anchor;
+ * `2/(W+cap)` is what it gets for TWO. Multiplying by `commonness` moves the bar between those two
+ * metric constants as the shared anchor moves across the anchor band: a unique anchor (`0`) leaves
+ * the operator's old `min_jaccard` in charge — a rare name on a wide fact is exactly the evidence
+ * the saturating metric exists to keep reachable — while an anchor at the ceiling (`1`) demands two
+ * anchors, because one is what a wide fact gets for free. The boundary is at `0.5`: below it one
+ * anchor is enough, above it the fact must share two.
+ *
+ * `min_jaccard` is still a lower bound and `0` still turns the gate off, so the knob keeps its
+ * meaning; the rarity term is what the old calibration was missing.
+ */
+export declare function entityEvidenceFloor(minJaccard: number, queryWidth: number, commonness: number): number;
 /**
  * The leg's raw score, in [0, 1] — see the module doc for the formula and the constants.
  *

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

@@ -22,6 +22,7 @@
  *
  * @module store/entity_sweep
  */
+import type { Awaitable } from '../interfaces/common.js';
 /**
  * What one bounded sweep pass did.
  *
@@ -73,10 +74,10 @@ export interface EntitySweepTarget<T extends EntitySweepRow> {
      * population — `total` is every stale row of the store's scope (memory: every ACTIVE fact;
      * knowledge: every chunk of the sweep's domain), `rows` is that population truncated.
      */
-    staleEntityBatch(limit: number): {
+    staleEntityBatch(limit: number): Awaitable<{
         total: number;
         rows: readonly T[];
-    };
+    }>;
     /**
      * Optional count-only read of the SAME population as {@link staleEntityBatch}'s `total`.
      *
@@ -84,7 +85,7 @@ export interface EntitySweepTarget<T extends EntitySweepRow> {
      * branch falls back to `staleEntityBatch(0).total`. The loop holds the guard for the whole pass and
      * each store is single-threaded, so the count cannot move between the two calls it makes.
      */
-    staleEntityCount?(): number;
+    staleEntityCount?(): Awaitable<number>;
     /** Re-extract one row's text and write that store's derived rows. May throw; the loop isolates. */
     extractAndWriteEntities(row: T): Promise<void>;
     /**