@avantf/dsh-mem 0.6.4 → 0.8.0

package/lib/engine/mem/interfaces/repositories.d.ts

@@ -0,0 +1,471 @@
+/**
+ * The document/relation repositories the store talks to (DB-1 boundary, DB-2 async, DB-3 ids).
+ *
+ * Everything here is a DOMAIN shape: no SQL, no `Db`, no `DbStatement`, no driver row class, no
+ * `TimeSql`, no rowid. `TimeRange` (the normalized window) crosses; how a driver turns it into a
+ * predicate is its own business. Rows are `FactRow` records because the store reads projections it
+ * does not own the shape of — the driver decides the columns, the port promises the fields the store
+ * names.
+ *
+ * METHOD NAMES mirror the DAOs DB-1 wrapped (`activeIds`, `countInStatus`, …) on purpose: the
+ * boundary was an extraction, not a redesign of what the store asks for. The async contract is in
+ * `./common.ts`; the ids are the backend's (`InsertRevisionOutcome`), and transactions live on the
+ * backend (`./storage_backend.ts#LifecycleService`).
+ *
+ * @module interfaces/repositories
+ */
+import type { ContradictionRecord, FactSourceView, MemoryKind, RelationInput } from '../../mem-contract/index.js';
+import type { GraphReader } from '../../graph-recall/index.js';
+import type { RelationVocabulary, SurfaceMatch } from '../store/relation_planner.js';
+import type { ExtractedEntity } from '../entities/extract.js';
+import type { TimeRange } from '../store/time_filter.js';
+import type { RelationCandidate, RelationDropReason, RelationTripleInput } from '../relations/index.js';
+import type { AliasRegistration } from '../relations/normalize.js';
+import type { CheckResult } from '../lifecycle/contradiction.js';
+import type { Awaitable } from './common.js';
+/** A facts row as the domain reads it. The driver owns the projection; the store names the fields. */
+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;
+}
+/**
+ * What one insert-or-ignore did.
+ *
+ * `inserted: false` means the content already exists and the driver 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.
+ */
+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[]>;
+    /** `mem_admin list` narrowed by an explicit time window (same order as `page`). */
+    pageTimeWindow(status: string, kind: MemoryKind | undefined, time: TimeRange, limit: number, offset: number, source?: string): Awaitable<FactRow[]>;
+    /** How many rows `pageTimeWindow` pages through — the page's `total`. */
+    countStatusTimeWindow(status: string, kind: MemoryKind | undefined, time: TimeRange, source?: string): Awaitable<number>;
+    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>;
+    /** v17: record a handle this fact used to carry, so an old title search still finds it. */
+    insertTitleAlias(factId: number, title: string): Awaitable<void>;
+    /** v17: carry a revision's aliases forward onto the revision that replaces it. */
+    copyTitleAliases(fromFactId: number, toFactId: number, currentTitle: string): Awaitable<void>;
+    /** v17: drop an alias that has become the row's current title (a correction back to it). */
+    dropTitleAlias(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[]>;
+    /**
+     * The FACT-level entity vocabulary: entity surfaces occurring in `text` that are linked to at
+     * least one ACTIVE fact through `fact_entities` — journal entries and notes with no relation edge
+     * included (docs/GRAPH_RECALL_AND_SEMANTICS.md §7.9).
+     *
+     * Deliberately NOT the graph reader's `entitiesIn`: that one only reports entities with edges,
+     * which is exactly the corpus the fact-level AND must NOT be limited to. `kind`/`source`/`time`
+     * are likewise NOT applied here — the vocabulary answers "is this a known name in the live
+     * corpus", while the page applies the caller's filters and an empty page falls back to fuzzy.
+     */
+    factEntitiesIn(text: string): Awaitable<SurfaceMatch[]>;
+    /**
+     * One fact-level AND page: ACTIVE facts that mention EVERY one of `query.entities` (see
+     * {@link FactsContainingAllQuery}). `total` is the number of such FACTS before paging.
+     */
+    factsContainingAll(query: FactsContainingAllQuery): Awaitable<FactContainingPage>;
+}
+/**
+ * The fact-level AND request behind `factsContainingAll` (docs/GRAPH_RECALL_AND_SEMANTICS.md §7.9).
+ *
+ * `entities` may be canonical names or registered aliases; a fact must mention EVERY resolved
+ * entity (AND, not "at least N"). Fewer than two distinct entities is not a multi-entity question
+ * and returns an empty page. The status filter is fixed to `active` — the public recall surface has
+ * no status parameter, and a fact-level answer is a page of the live corpus.
+ */
+export interface FactsContainingAllQuery {
+    entities: readonly string[];
+    /** `facts.kind`; omitted = BOTH layers (the documented `kind=all` default). */
+    kind?: MemoryKind;
+    /** `fact_sources.ref`, the same source axis `mem_recall.search` exposes. */
+    source?: string;
+    /** The caller's explicit time filter, on `facts` (the same normalized window the legs use). */
+    time?: TimeRange;
+    offset: number;
+    limit: number;
+}
+/** One page of the fact-level AND answer: ACTIVE fact rows plus the fact count before paging. */
+export interface FactContainingPage {
+    total: number;
+    rows: FactRow[];
+}
+/** 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 write/read shapes (STRUCTURED_RELATIONS §四/§七, RELATIONAL_RECALL §4.3).
+ *
+ * These are DOMAIN reports: they say how many edges one write produced and why the rest were
+ * refused. The SQL that produces them lives in the SQLite driver; declaring the shapes here is what
+ * lets `interfaces/` stay free of `db/graph.ts`.
+ */
+export type EdgeSourceTriple = RelationTripleInput;
+/** Why one extracted triple did not become an edge: the policy's reasons plus the storage step's. */
+export type EdgeDropReason = RelationDropReason | 'self-relation';
+/** One dropped triple, kept as EVIDENCE for the coverage report (§4.3 "记录抽取覆盖率/失败样本"). */
+export interface EdgeDropSample {
+    fact_id: number;
+    subj: string;
+    pred: string;
+    obj: string;
+    /** The confidence the policy computed for it (below `EDGE_MIN_CONFIDENCE` for `low-confidence`). */
+    confidence: number;
+    reason: EdgeDropReason;
+}
+/** What one fact's edge write did. */
+export interface EdgeWriteReport {
+    /** Rows actually inserted. */
+    written: number;
+    /** Rows already present (same fact/subject/predicate/object) — a repeat write's normal outcome. */
+    duplicates: number;
+    /** Rows the policy refused. */
+    dropped: number;
+    /** Up to the caller's `samples` cap, why they were refused. */
+    samples: EdgeDropSample[];
+}
+/** What one {@link RelationRepository.rebuildEdgesForFact} pass did. */
+export interface EdgeRebuildReport extends EdgeWriteReport {
+    /** Edges deleted before re-deriving (always the non-explicit ones). */
+    removed: number;
+}
+/** Which facts one `reextractEdges` pass selects. */
+export type EdgeReextractMode = 'stale' | 'all';
+/** Options for {@link RelationRepository.reextractEdges}. */
+export interface EdgeReextractOptions {
+    /** Facts one pass may rewrite (the driver's own bounded batch default). */
+    budget?: number;
+    /** `false` (default): only facts whose edges are older than the current extractor version. */
+    all?: boolean;
+    /** Cap on the failure samples returned (default 5). */
+    samples?: number;
+}
+/** What one `reextractEdges` pass did. */
+export interface EdgeReextractReport {
+    mode: EdgeReextractMode;
+    /** Facts selected and re-derived (its budget when it filled it). */
+    facts: number;
+    /** Facts whose edge rows were replaced. */
+    rewritten: number;
+    /** Facts still waiting for a pass (`stale`: edges older than the current version). */
+    deferred: number;
+    edgesRemoved: number;
+    edgesCreated: number;
+    dropped: number;
+    samples: EdgeDropSample[];
+    /** Edges deleted because their fact is not a note (§四/§七). */
+    journalEdgesRemoved: number;
+}
+/** How many edges each extraction version has (the version axis of the coverage report). */
+export interface EdgeVersionCount {
+    version: number;
+    edges: number;
+}
+/** The graph's coverage, as one read (§R2 "归一覆盖率报告" / §R6 observability). */
+export interface GraphCoverageReport {
+    activeFacts: number;
+    /** Active facts the string extractor found at least one triple for. */
+    factsWithTriples: number;
+    /** Active facts with at least one edge (any version). */
+    factsWithEdges: number;
+    /** Active facts the version rule still selects (`reextractEdges()` would visit them). */
+    factsStale: number;
+    edges: number;
+    edgesByVersion: EdgeVersionCount[];
+    /** Extraction version a real pass would stamp today. */
+    extractionVersion: number;
+    entities: number;
+    entityAliases: number;
+    predicates: number;
+    predicateAliases: number;
+    /** `factsWithTriples / activeFacts` — how much of the corpus yields any relation at all. */
+    tripleCoverage: number;
+    /** `factsWithEdges / factsWithTriples` — how much of that survived normalization + the floor. */
+    relationCoverage: number;
+    /** Up to `samples` triples the current rules would refuse, with the reason. */
+    samples: EdgeDropSample[];
+}
+/**
+ * The relation graph: caller-stated/explicit edges, the versioned extractor's derived edges and the
+ * read-only walkers. The SQL stays in the driver.
+ */
+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 driver loaded when it was built.
+     * A remote driver 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;
+    }>;
+}
+/** One contradiction pair, as the contract reports it. */
+export interface ConflictPair {
+    /** Row id of the pair — the handle `contradict_resolve` takes. */
+    contradiction_id: number;
+    fact_a: number;
+    fact_b: number;
+    score: number;
+}
+/** A row of the conflict log as stored: the pair plus its adjudication state. */
+export interface StoredConflict {
+    id: number;
+    fact_a: number;
+    fact_b: number;
+    score: number;
+    /** 0 = open, 1 = closed (see `resolution` / `loser_fact_id` for how). */
+    resolved: number;
+    resolution: string | null;
+    loser_fact_id: number | null;
+    /** `auto` (a fact left the corpus) or `verdict` (explicit adjudication). */
+    resolved_by: string | null;
+}
+/** 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[]>;
+}
+/** 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>;
+}
+/** One conflict-check result (`lifecycle/contradiction.ts#CheckResult`), re-exported for driver authors. */
+export type { CheckResult };

package/lib/engine/mem/interfaces/search_index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The search contract (DB-3, `docs/DB_DRIVER_LAYOUT.md` §二).
+ *
+ * The interface takes the CALLER'S QUERY, never a query-expression in a backend's syntax: the driver
+ * owns its tokenizer, its full-text dialect and its rank sign. That is what lets a second driver
+ * 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 driver itself (SQLite: FTS triggers); {@link SearchIndex.rebuild} is
+ * the repair path a caller may run when the derived index must be re-derived from the source rows.
+ *
+ * @module interfaces/search_index
+ */
+import type { MemoryKind } from '../../mem-contract/index.js';
+import type { TimeRange } from '../store/time_filter.js';
+import type { Awaitable } from './common.js';
+/** One title-search row (`mem_recall.titles`). */
+export interface TitleMatch {
+    fact_id: number;
+    /** The row's CURRENT title — the handle a caller should act on. */
+    title: string;
+    /**
+     * The title TEXT the query matched: the current title, or one of the aliases a corrected
+     * transaction used to carry (v17). A driver that keeps no alias set reports `title` here.
+     */
+    matched_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 driver'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 pure time window — `mem_recall.search` with no query (`mode:"time"`, RECALL_INTERFACE §2.4).
+ *
+ * The window IS the question, so the filter is the whole request: status is always ACTIVE (a recall
+ * reads the current corpus), and the rows come back newest-first along the window's OWN axis
+ * (`time.field`). That order is why the domain `TimeRange` travels here instead of a compiled
+ * predicate.
+ */
+export interface TimeWindowQuery {
+    time: TimeRange;
+    kind?: MemoryKind;
+    source?: string;
+}
+/**
+ * A full-text hit: the fact id and the backend's own relevance rank.
+ *
+ * HIGHER IS ALWAYS BETTER. The driver 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;
+}
+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[]>;
+    /** How many ACTIVE facts fall inside a pure time window (`mode:"time"`'s `total`). */
+    countInTimeWindow(query: TimeWindowQuery): Awaitable<number>;
+    /** One page of that window, newest first along the window's own axis. */
+    timeWindowRows(query: TimeWindowQuery & {
+        limit: number;
+        offset: number;
+    }): Awaitable<number[]>;
+    /** Title search: title-equal, else the driver's own title index / substring fallback. */
+    searchTitles(query: TitleQuery): Awaitable<TitleMatch[]>;
+    /** Clear and re-derive the index from the source rows. */
+    rebuild(): Awaitable<void>;
+}

package/lib/engine/mem/interfaces/storage_backend.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The backend a driver OPENS (DB-1 boundary; DB-2 async; DB-3 ids/search/migrations).
+ *
+ * `MemoryStore` receives this object, never a `Db`, a DAO or SQL. Which driver produced it is the
+ * composition root's business (`storage/create.ts`); the store only sees the port shapes declared in
+ * this directory.
+ *
+ * `keyValue` and `lifecycle` are connection-scoped and therefore part of the backend rather than the
+ * repositories: retrieval health lives in the backend's own side table, and transactions / the
+ * lifecycle tick are things only the driver can implement (a remote backend must give the host an
+ * async unit of work — see {@link LifecycleService}).
+ *
+ * `relationalHandle` is the ONE transitional hole in the abstraction: the CLI's relation-backfill
+ * commands and the diagnostics still speak SQL through `Db` (docs/DB_DRIVER_LAYOUT.md §一 rule 4 is
+ * about the STORE and the retrieval paths). It is declared as `unknown` on purpose — a portable
+ * interface cannot name a driver type — and a caller that needs it casts explicitly.
+ *
+ * @module interfaces/storage_backend
+ */
+import type { FactsExportDocument } from '../facts_io.js';
+import type { MaintenanceResult } from '../lifecycle/maintenance.js';
+import type { TickResult } from '../lifecycle/tick.js';
+import type { EntitySweepReport } from '../store/entity_sweep.js';
+import type { RestoreOptions, RestoreReport } from '../store/facts_restore.js';
+import type { Config } from '../../mem-contract/index.js';
+import type { StorageCapabilities } from './capabilities.js';
+import type { Awaitable } from './common.js';
+import type { MigrationRunner } from './migrations.js';
+import type { ContradictionRepository, KeyValueRepository, MemoryRepository, RelationRepository, SourceRepository } from './repositories.js';
+import type { SearchIndex } from './search_index.js';
+/**
+ * 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 driver runs them. The callback
+ * form is deliberate: no driver 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: Config, opts: {
+        clock: number;
+        budget?: number | null;
+    }): Awaitable<TickResult>;
+    maintenance(config: Config, opts?: {
+        clock?: number;
+        budget?: number | null;
+    }): Awaitable<MaintenanceResult>;
+    restore(doc: FactsExportDocument, reindexEntities: (budget?: number) => Promise<EntitySweepReport>, options?: RestoreOptions): Promise<RestoreReport>;
+}
+/** The composition-root result: what a driver's `open()` returns and the store is built over. */
+export interface StorageBackend {
+    /** The driver that opened this backend (`StorageDriver.name`) — a label, never branched on above. */
+    readonly kind: string;
+    /** What this driver declared it can do at open (docs/DB_DRIVER_LAYOUT.md §二). */
+    readonly capabilities: StorageCapabilities;
+    /** The facts aggregate (named `facts` per 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 driver's own relational handle, for the transitional SQL-speaking operator surfaces. A
+     * driver that has none omits it; callers must fail loudly rather than invent one.
+     */
+    relationalHandle?(): unknown;
+    close(): Awaitable<void>;
+}