@avantf/dsh-mem 0.3.1 → 0.4.0

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

@@ -0,0 +1,543 @@
+import { type Config, type ContradictionRecord, type FactDetail, type FactPage, type FloorProfile, type RecallResult, type RememberResult, type TrustDiagnostic, type VectorsDiagnostic, type VectorsFixReport } from '../../mem-contract/index.js';
+import type { Reranker, SemanticBackend, VectorStore } from '../../mem-retrieval/index.js';
+import type { Db } from '../db/conn.js';
+import { type LexicalProbe } from './lexical.js';
+import { type FloorLeg } from './floors.js';
+import { type TriplePattern } from '../entities/extract.js';
+import { type Sig } from '../lifecycle/contradiction.js';
+import { type MaintenanceResult } from '../lifecycle/maintenance.js';
+import { type TickResult } from '../lifecycle/tick.js';
+/**
+ * Result shapes live in `@avantf/mem-contract` (single source for tool/UI payloads); these
+ * aliases keep the long-standing `@avantf/mem` export names working for consumers.
+ */
+export type { DetectedContradiction, RememberResult as AddResult } from '../../mem-contract/index.js';
+/**
+ * Facts one derived-state sweep pass may rebuild (`reindexEntities`'s default budget).
+ *
+ * Bounds MEMORY, not only mission: the pass selects `content` for every row it takes, so an
+ * "unbounded" pass (the CLI used to ask for `Number.MAX_SAFE_INTEGER`) builds an array of every
+ * stale fact's text before rebuilding the first one. Callers that want the corpus drained loop
+ * until `deferred === 0` instead.
+ */
+export declare const ENTITY_SWEEP_BATCH = 2000;
+/** What one derived-state sweep pass did (see `MemoryStore.reindexEntities`). */
+export interface EntitySweepReport {
+    /**
+     * Facts this pass RE-EXTRACTED, i.e. its batch size when it filled it. Counts rows VISITED and
+     * re-stamped, not rows whose extraction output differs — the stamp is what makes the corpus
+     * current, so a row re-extracted to the same names still counts (and is not rebuilt again).
+     */
+    rebuilt: number;
+    /** Facts still written by older rules after this pass. */
+    deferred: number;
+    /** Another pass was already running, so this one did nothing (`deferred` is still current). */
+    skipped: boolean;
+}
+/** What one bounded conflict-drain pass did (see `MemoryStore.drainConflicts`). */
+export interface ConflictDrainReport {
+    /** Pairs newly logged by this pass. */
+    logged: Sig[];
+    /**
+     * Rows the pass COMPLETED — the embedding leg held their vector in the live index, so the stamp
+     * moved. Deliberately not the batch size: a row whose vector the index cannot serve stays queued
+     * (see `CheckResult`), which is why this can be 0 while `pending` is not.
+     */
+    checked: number;
+    /** Rows still queued after this pass (including any it could not complete). */
+    pending: number;
+}
+/**
+ * Counts-only view of one conflict pass, for the `maintenance` payload: the pairs themselves are
+ * the `contradict_check` payload, and a settings-page click has no use for a list of them.
+ */
+export interface ConflictSweepCounts {
+    /** Rows the pass completed (the embedding leg held their vector). */
+    checked: number;
+    /** Pairs it logged. */
+    logged: number;
+    /** Rows still queued afterwards. */
+    pending: number;
+}
+/**
+ * Outcome of adjudicating a conflict (see `MemoryStore.resolveContradiction`). `reason` is
+ * present only on a refusal, so a caller can tell "the pair is closed" from "your request
+ * named a fact that is not in the pair".
+ */
+export interface ContradictionResolution {
+    resolved: boolean;
+    contradiction_id: number;
+    /** The fact that was archived as the loser, when the verdict named one. */
+    archived_loser: number | null;
+    /**
+     * Why the verdict was refused. `already_resolved` means the pair carries a verdict already — see
+     * {@link MemoryStore.resolveContradiction} for why a second one is refused rather than applied.
+     */
+    reason?: 'not_found' | 'already_resolved' | 'loser_not_in_pair' | 'loser_requires_true_positive';
+}
+export interface SearchInput {
+    query: string;
+    category?: string;
+    limit?: number;
+    /** Also fuse the HRR entity-probe path (used by `recall.probe`). */
+    includeHrr?: boolean;
+    /**
+     * Record retrieval stats for the returned facts (default true). Cross-store
+     * `kb_query` sets this false and marks only the hits it actually returns, so
+     * router-side filtering cannot refresh the dormancy clock of unseen facts.
+     */
+    track?: boolean;
+    /**
+     * Pre-encoded query vector, when the caller already has one. `runtime.query` encodes a
+     * cross-store query ONCE and hands the same vector to both stores (they share the same
+     * backend and model), instead of each leg paying for its own encode. The store does not
+     * verify it, so it must come from the same backend.
+     */
+    queryVector?: Float32Array;
+    /** Per-call output token budget; `0` = unlimited, omitted = `retriever.max_output_tokens`. */
+    maxTokens?: number;
+    /**
+     * Relevance-floor profile for this query. Omitted = the default policy: the configured (strict)
+     * floors, and if they empty the result while having dropped candidates, ONE relaxed pass
+     * (`store/floors.ts`'s `LOOSE_FLOORS`) before answering. `'strict'` asserts the configured floors
+     * with no fallback — what the UI's 严格 mode asks for, so the panel can show the honest strict
+     * outcome and the drop count. `'loose'` applies the relaxed floors outright.
+     */
+    floors?: FloorProfile;
+    /**
+     * Which legs a `'loose'` pass may lower (see `store/floors.ts`). Internal: an omitted value lets
+     * the default policy derive it from the strict pass's own drop report, while the cross-store
+     * router pins the MERGED strict pass's dropping legs on its second call — only the merged result
+     * knows which legs were the problem for the user's one question.
+     */
+    relaxLegs?: readonly FloorLeg[];
+    /**
+     * Emit a `kind: 'memory'` health event for this search (default true). The cross-store router
+     * sets it false: it fuses this leg with the knowledge leg and records ONE `kind: 'cross'`
+     * event, so `queries` counts user questions instead of legs (DESIGN §20.5). Distinct from
+     * `track`, which is about the dormancy clock — a caller may want one without the other.
+     */
+    recordStats?: boolean;
+}
+export declare class MemoryStore {
+    private readonly db;
+    private readonly config;
+    private readonly semantic;
+    private readonly vstore;
+    private readonly reranker;
+    private readonly contradictions;
+    private readonly facts;
+    private readonly entities;
+    private readonly triples;
+    /**
+     * The tokenizer `facts_fts` was ACTUALLY built with, read from the database at open.
+     *
+     * Not `resolveFtsTokenizer()`: `CREATE VIRTUAL TABLE IF NOT EXISTS` never rebuilds an existing
+     * table, so a database created under another SQLite build keeps the tokenizer it was born with,
+     * and building MATCH expressions for the wrong one is silent zero recall (see `db/tokenizer.ts`).
+     */
+    private readonly ftsTokenizer;
+    /** In-flight guard for `reindexEntities` (see there: the periodic callers can overlap). */
+    private entitySweepInFlight;
+    /**
+     * Where the next conflict drain resumes (see `checkContradictions`). A scheduling cursor, not
+     * derived state: nothing is lost when it resets, and the queue itself is in the database.
+     */
+    private conflictDrainCursor;
+    constructor(db: Db, config: Config, semantic: SemanticBackend, vstore: VectorStore, reranker: Reranker, 
+    /** The store's database path, used ONLY to name the vector index snapshot beside it. */
+    dbPath?: string);
+    /**
+     * One automatic trust/lifecycle pass (spec §5): advance the active-day clock
+     * (when trust is enabled), run the tick, and evict archived/purged vectors from
+     * the live index. Called at startup, from the heartbeat, and by `maintenance()`.
+     */
+    trustTick(opts?: {
+        budget?: number | null;
+    }): TickResult;
+    /** Identity of the vector space this store currently writes into (`vectorSpaceId`). */
+    private vectorSpace;
+    /**
+     * Rebuild the in-memory vstore from persisted `facts.semantic_vector` BLOBs.
+     * Without this the semantic path is silently empty after every process restart
+     * (the DB is the authoritative vector store; the vstore is a derived read model).
+     *
+     * Only ACTIVE facts are indexed: archived facts are filtered out of every
+     * retrieval path anyway, so loading them would only grow the index forever.
+     * `archive()` evicts and `restore()` re-adds, keeping the invariant.
+     */
+    private reloadIndex;
+    add(content: string, category?: string, ttlDays?: number): Promise<RememberResult>;
+    /**
+     * Write-path contradiction detection (DESIGN §11): check the fact that was just
+     * written against the corpus, then report its FULL open-conflict set.
+     *
+     * The check's own return value is not enough: `maybeLog` skips pairs that are already
+     * open, so what it returns is "what this pass inserted" — while the caller's question is
+     * "what does this write conflict with?". Reporting only the new rows made an update that
+     * merged into an already-conflicting fact look clean.
+     *
+     * Best-effort — a detection failure must never fail the write, and the fact stays PENDING for
+     * the next `contradict_check`. `complete` is what enforces that second half: it is true only
+     * when nothing went wrong AND the pass held this fact's vector, so a caught failure can never
+     * be mistaken for a finished check (an earlier version returned `[]` for both and the caller
+     * stamped the marker anyway — a permanent, silent exemption).
+     */
+    private detectContradictions;
+    /** Best-effort semantic indexing: encode the fact and add it to the vstore. */
+    private maybeIndexSemantic;
+    update(fact_id: number, content: string, category?: string, ttlDays?: number): Promise<RememberResult>;
+    remove(fact_id: number, reason?: string): boolean;
+    archive(fact_id: number, reason?: string): boolean;
+    /**
+     * Bring an archived fact back (spec §2.6): a `forgot` fact is lifted to
+     * `recall_floor` (otherwise the very next tick would re-archive it, R4), the
+     * idle clock is refreshed (otherwise an `idle`-archived fact dies again, R18),
+     * and `settle_clock` moves to now so the downtime is not charged.
+     */
+    restore(fact_id: number): boolean;
+    helpful(fact_id: number): number | null;
+    unhelpful(fact_id: number): number | null;
+    /**
+     * Explicit feedback (spec §2.4). Pinned/archived rows only move `helpful_count`
+     * (R7); otherwise the decay is settled first, then `±feedback_delta`, pin at the
+     * permanent threshold (snap to 1.0) or archive immediately at the forget line.
+     */
+    private applyFeedback;
+    /** Permanent-memory administration (spec §6). */
+    pin(fact_id: number): boolean;
+    unpin(fact_id: number): boolean;
+    /**
+     * Trust/forgetting diagnostics (spec §6, R17/R24): the quota is PER FACT, so the
+     * report exposes "facts that consumed quota today" and "total effective gains"
+     * rather than a meaningless global remaining.
+     */
+    trustDiagnose(): TrustDiagnostic;
+    get(fact_id: number): FactDetail | null;
+    private triplesOf;
+    /**
+     * One page of facts, newest first.
+     * @param category - optional category filter.
+     * @param status - `active` (default) or `archived`.
+     * @param limit - page size.
+     * @param offset - page offset (0-based).
+     * @returns the page, the page size (`count`), the matching total, and whether
+     * more rows remain after this page.
+     */
+    list(category?: string, status?: string, limit?: number, offset?: number): FactPage;
+    countByStatus(): {
+        active: number;
+        archived: number;
+    };
+    /** Run one incremental contradiction-detection pass; returns newly logged pairs. */
+    /**
+     * Drain the DURABLE pending queue, bounded by `budget`.
+     *
+     * These are facts whose embedding-leg check could not run when they were written (no vector —
+     * the embedder was unavailable). The queue is `facts.conflict_checked`, not an in-process Set, so
+     * it survives a restart and cannot grow without bound as a memory structure.
+     *
+     * The stamp follows the CHECK, not the selection: a row is marked checked only when the pass
+     * actually held its vector (see `CheckResult`). The queue predicate asks the DATABASE for
+     * `semantic_vector IS NOT NULL`, which is a different question from "the live index can serve
+     * it" — a vector written by another process, or dropped while this one rebuilt its index, is in
+     * the column and not in the index. Stamping those was a permanent exemption dressed up as a
+     * completed check; leaving them queued keeps `conflict_pending` honest, and `vectors_fix` (which
+     * resets the marker when it re-encodes) is what clears them.
+     *
+     * What the drain guarantees instead of "every selected row is stamped" is that it always MOVES:
+     * rows are taken above `conflictDrainCursor`, so an un-completable row cannot hold up the ones
+     * behind it. A restart resets the cursor, which costs one extra pass over the head and is why
+     * this is a scheduling cursor rather than derived state.
+     *
+     * A throw keeps the batch queued too — `checkMany` never returns, so nothing is stamped.
+     */
+    drainConflicts(budget?: number): ConflictDrainReport;
+    /** {@link drainConflicts}, reduced to the pairs it logged (the `contradict_check` payload). */
+    checkContradictions(budget?: number): Sig[];
+    /**
+     * One bounded conflict pass for {@link maintenance}, reduced to COUNTS.
+     *
+     * `maintenance` is the surfaces' "clean up now" entry (the settings page and the MCP tool call
+     * it), and the conflict queue is the other half of the derived state the entity sweep handles: a
+     * database upgraded from v5 has every vector-bearing row queued at once, and without this the
+     * only way to drain it was the explicit `contradict_check` action. Bounded like the entity sweep
+     * (one batch), so a settings-page click stays a click; the CLI is the surface that loops.
+     */
+    private sweepConflicts;
+    /** Async bootstrap the semantic backend (download/config model) without blocking. */
+    warmupSemantic(): Promise<boolean>;
+    /** List contradiction candidates (`resolved` 0 = open, 1 = closed with a recorded verdict). */
+    listContradictions(opts?: {
+        resolved?: number;
+        category?: string;
+        threshold?: number;
+        limit?: number;
+    }): ContradictionRecord[];
+    /**
+     * Adjudicate one logged conflict — the outlet the detector never had.
+     *
+     * Detection was complete but one-way: a pair was recorded and `resolveForFact` retired it when
+     * a fact left the ACTIVE corpus, yet nothing could say "this pair is decided" while both
+     * revisions stayed put. The DAO even had `resolve()` with no caller, so the open list could
+     * only grow. Two verdicts are meaningful:
+     *
+     *  - `false_positive`: both statements are true, the pair is closed and both facts stay;
+     *  - `true_positive` + `loser_fact_id`: the loser was wrong, so it is ARCHIVED — which is also
+     *    what retires every other open conflict naming it, and why the loser must be one of the
+     *    two facts in this pair.
+     *
+     * The verdict is recorded on this row either way: `archive()` short-circuits for a fact that
+     * is already archived, and the row would otherwise stay open on a technicality.
+     */
+    resolveContradiction(id: number, resolution: 'true_positive' | 'false_positive', loserFactId?: number): ContradictionResolution;
+    /**
+     * Semantic-index health for the ACTIVE corpus (the only thing the index serves):
+     *  - `missing`     active facts with no persisted vector at all;
+     *  - `stale`       active facts whose persisted vector has the wrong dim
+     *                  (semantic.dim changed) — needs a re-encode;
+     *  - `indexed`     vectors currently in the live index;
+     *  - `unindexed`   active facts with a usable persisted vector that the live
+     *                  index does not hold (restart/index loss);
+     *  - `store`       the backend actually serving reads (`auto` migrates at a threshold).
+     *  - `space_stale` vectors written in a DIFFERENT vector space (another model, or a store
+     *                  upgraded past the space id) — usable bytes, incomparable scores.
+     * `total`/`with_semantic` still describe the whole table (including archived).
+     */
+    vectorsDiagnose(): VectorsDiagnostic;
+    /**
+     * ONE read+decode pass over the persisted vectors, shared by diagnose and fix
+     * (the two methods used to re-scan and re-decode the same blobs 4-5× per call).
+     */
+    private classifyVectors;
+    /**
+     * Repair the semantic read model:
+     *  (a) reload persisted, dim-valid vectors missing from the live index
+     *      (restart / index loss — needs no model),
+     *  (b) drop persisted vectors whose dim no longer matches `semantic.dim` so a
+     *      re-encode can replace them (never `add()` a stale vector — the store
+     *      throws on dim mismatch),
+     *  (c) encode active facts that have no vector yet (needs the semantic backend),
+     *  (d) re-encode vectors written in ANOTHER vector space (a model swap, or the one-time
+     *      adoption of a store predating the space id). Deliberately here and not at open: this is
+     *      the only path that re-encodes the whole table, so it is an explicit, counted action.
+     * `dry_run` previews every count without writing — and without loading the model, which is why
+     * the preview also reports `would_warm` (see the contract's `VectorsFixReport`).
+     */
+    vectorsFix(dryRun?: boolean): Promise<VectorsFixReport>;
+    /**
+     * One lifecycle pass, owned by the store so the DB writes and the live-index
+     * invariant (ACTIVE vectors only) are maintained in ONE place — the runtime no
+     * longer has to patch the index behind the store's back.
+     *
+     * It also runs ONE bounded derived-state sweep pass, which is why it is async: `entities` is
+     * what the sweep rebuilt and what it still owes (`deferred`). One pass, not a loop — this is
+     * reachable from a settings-page button and an MCP call, so it must not block on a whole stale
+     * corpus; operators who want it drained loop on `reindexEntities` until `deferred === 0` (the
+     * CLI does). It deliberately does not sit behind `heartbeat_minutes`, which can be 0.
+     */
+    maintenance(): Promise<MaintenanceResult & {
+        entities: EntitySweepReport;
+        conflicts: ConflictSweepCounts;
+    }>;
+    /**
+     * Re-extract the entity/triple rows of facts written by OLDER extraction rules (bounded).
+     *
+     * The memory-side counterpart of `KnowledgeStore.reindex`'s entity leg, and the reason
+     * `facts.entities_version` exists: without it a change to the extraction rules could only reach
+     * facts written afterwards, so the corpus would carry two vintages indefinitely and retrieval
+     * quality would depend on when a fact happened to be written. The version covers the RULES, not
+     * which tagger happened to produce the tokens — the tagger is an optional dependency loaded
+     * asynchronously, and a process that fails to load it falls back to regex; folding that into the
+     * version would make a capability failure schedule a corpus-wide rebuild with the WORSE extractor.
+     *
+     * One transaction per fact: the entity rows, the triple rows, the HRR bundle (which is derived
+     * FROM the entity names) and the version stamp all move together or not at all. The semantic
+     * vector is untouched — it encodes the CONTENT, which is unchanged — but `conflict_checked` is
+     * RESET, because both legs of the conflict check read exactly what this rebuilt (see
+     * `requeueConflictCheck`).
+     *
+     * Awaited by `maintenance` (one batch), so the caller knows the batch is done when it returns;
+     * `deferred` is what the next pass still has to do. Callers that want the whole corpus drained
+     * loop until `deferred === 0` — `budget` bounds MEMORY as well as mission, since the pass reads
+     * every selected row's `content` before rebuilding the first one.
+     *
+     * The in-flight guard is here rather than at the callers because the callers CAN overlap: the
+     * plugin's heartbeat and `maintenance` are both periodic, and `staleEntityRows` is ORDERED, so
+     * two concurrent passes would select the same rows and re-tag them twice. Overlap is not
+     * corruption (each fact is stamped in its own transaction) — it is duplicated mission in a
+     * single-threaded process. A pass that finds one running reports `skipped` and does nothing.
+     *
+     * `budget` is clamped at 0: SQLite reads a negative LIMIT as "no limit" (`LIMIT -1`), so a
+     * caller asking for "-1 rows" would silently get the whole corpus — the opposite of bounded.
+     */
+    reindexEntities(budget?: number): Promise<EntitySweepReport>;
+    /**
+     * A fact left the ACTIVE corpus: retire the open conflicts that name it, so
+     * `contradict` never reports a pair whose revision is archived and repeated
+     * archive/restore cycles cannot stack duplicates (see
+     * `ContradictionsDao.resolveForFact`).
+     */
+    private retireConflicts;
+    /** Drop vectors of archived/purged facts from the live index (batched). */
+    private evictVectors;
+    /**
+     * Entities that co-occur with `entity` across ACTIVE facts, ranked by occurrence
+     * count. Archived (incl. superseded) facts are excluded — their entities are not
+     * part of the live graph.
+     */
+    related(entity: string, limit?: number, category?: string): {
+        entity: string;
+        count: number;
+    }[];
+    /** Two-hop traversal: subj -pred-> mid, mid -second_pred-> obj. Returns the second-hop facts. */
+    chain(subj: string, pred?: string, secondPred?: string, limit?: number): Promise<RecallResult>;
+    /** Facts whose entity set contains ALL given entities (AND-join). */
+    reason(entities: string[], limit?: number): Promise<RecallResult>;
+    /** Hybrid search over the memory corpus (semantic + FTS + entity Jaccard [+ HRR probe] via fusion). */
+    search(input: SearchInput): Promise<RecallResult>;
+    /**
+     * This store's half of the shared orchestration (`store/hybrid.ts`): the legs, the text load, the
+     * fact→hit mapping, and what to do with the hits the caller actually receives.
+     */
+    private hybridDeps;
+    /**
+     * The memory legs: semantic, FTS, entity Jaccard, and — for `recall.probe` — the HRR probe.
+     *
+     * Every non-semantic leg is CAPPED. Fusion only ever keeps `overFetch` entries, so a leg returning
+     * the whole matching corpus (measured: the FTS leg returned all 33000 facts for a common phrase,
+     * the entity leg 6600) made `fuse` normalize and sort the corpus per query. 4× the pool is
+     * deliberate headroom: each leg must be able to fill the pool on its own.
+     *
+     * The cap is score-transparent for a leg that hands its entries over in ITS OWN SCORE ORDER —
+     * `fuse` scales by each leg's maximum, an entry no cap can remove, so a trimmed tail cannot
+     * rescale the survivors. That covers the Jaccard and FTS legs. It does NOT cover the HRR leg, whose
+     * candidates arrive in the JACCARD leg's order (or by recency in its fallback), so its cap can
+     * remove its own highest scorer and `v / max` really does move. Accepted — the cap bounds per-query
+     * mission and the pool is reranked afterwards — but do not read these scores as comparable across
+     * different cap/over-fetch settings; see `docs/PROVENANCE_REVIEW.md` N5 for the missing differential.
+     */
+    private searchLegs;
+    /**
+     * Whether the configured reranker is actually in use — the two flags a retrieval event
+     * carries. Exposed so the cross-store router can report ONE event for a merged query with the
+     * same honesty as a single-store search (both stores share this adapter, and the derivation lives
+     * in `store/hybrid.ts` rather than being re-spelled per store).
+     */
+    rerankState(): {
+        used: boolean;
+        fallback: boolean;
+    };
+    /**
+     * The one fact→RecallHit mapper (kind/source_ref/entities shape lives here ONLY;
+     * chain/reason/ask/search all used to carry byte-identical copies, three of them
+     * with an N+1 entity load each). Facts have no knowledge-base taxonomy, so
+     * `domain`/`source` are null — that is what keeps a `domain`-filtered cross query
+     * from ever matching a memory hit.
+     */
+    private factHits;
+    /**
+     * Record a RECALL and reinforce the facts (spec §2.3): usage stats always move,
+     * the trust bonus is quota-limited (per fact, calendar 24h), zero-gain recalls
+     * cost nothing, and a recall can never push a fact to permanent (D11).
+     *
+     * Public so `runtime.query` can reinforce ONLY the merged hits it actually
+     * returns, after the router's kind/domain/source filtering (R5/R21).
+     */
+    reinforce(ids: number[]): void;
+    /**
+     * Load the persisted retrieval-health counters, and write the current ones back.
+     *
+     * A snapshot written by an older build (or a corrupt row) must not break startup, so a parse
+     * failure leaves the live counters alone — `restoreRetrievalHealth` validates the shape.
+     */
+    private restoreHealth;
+    /**
+     * Flush the counters so a restart does not reset the picture (see `RETRIEVAL_HEALTH_KEY`).
+     *
+     * Called by `maintenance()` and by the runtime on shutdown — NOT from a `close()`, because the
+     * runtime owns the database handle.
+     */
+    flushHealth(): void;
+    /** Retrieval bookkeeping: `retrieval_count` + the "last used" clock (spec §2.5). */
+    private touchUsage;
+    /**
+     * Semantic leg. `queryVector` short-circuits the encode when the caller already
+     * encoded this exact query (the cross-store router does, for both stores at once);
+     * `onVector` publishes the vector this leg actually used, so the relaxed retry pass can reuse it
+     * instead of re-encoding (performance review §7.7 / P8).
+     */
+    private semanticPath;
+    /**
+     * HRR entity-probe path: phase similarity between the query's entity bundle and
+     * each active fact's persisted HRR vector. Recalls facts whose entities relate to
+     * the probe even when surface text shares no FTS trigrams.
+     */
+    private hrrPath;
+    /**
+     * Direction-aware question answering over SPO triples.
+     * Parse the query into a TriplePattern, match triples by the filled slots
+     * (unfilled = wildcard), and rank the owning facts. Direction is preserved by
+     * the triple's (subj, pred, obj) roles.
+     */
+    ask(query: string, limit?: number): Promise<RecallResult>;
+    /** Direction-aware answer over SPO triples from an explicit pattern. */
+    askByPattern(pattern: TriplePattern, limit?: number): Promise<RecallResult>;
+    /** One-shot flag for the probe fallback warning (see `hrrPath`). */
+    private hrrFallbackWarned;
+    /**
+     * Sync relevance probe for the plugin's conditional hint (DESIGN §12): how many of `text`'s
+     * terms this store already holds. `store/lexical.ts` carries why it is lexical rather than
+     * semantic, why it must be synchronous, and how the bar itself was measured.
+     */
+    lexicalProbe(text: string, stopAt?: number): LexicalProbe;
+    private ftsPath;
+    /**
+     * Jaccard leg over the precomputed candidate set (see `search`): the candidates are the facts
+     * sharing at least one query entity, pre-ranked by how many they share and already capped.
+     */
+    private jaccardPath;
+    /**
+     * Insert (or resolve to) a fact row.
+     *
+     * `category` / `ttlDays` are `undefined` when the CALLER specified nothing — the
+     * distinction is load-bearing. A duplicate-content hit must not clobber the existing
+     * row's values with the insert defaults: re-adding a fact without a category used to
+     * reset it to `general`, and reviving an archived one silently cleared an explicit TTL.
+     * The rule for all three branches is therefore: an explicitly provided value lands, an
+     * omitted one keeps what the row already has, and a brand-new row falls back to the
+     * defaults (`general` / `0`).
+     */
+    private persistFact;
+    /**
+     * Link the revision chain and archive the superseded fact — on both the fresh-insert
+     * and duplicate-content branches.
+     *
+     * @returns the superseded fact id whose vector must leave the live index, or null.
+     *   The caller evicts it AFTER the surrounding transaction commits: evicting inside
+     *   would desync the index from the DB on a rollback.
+     */
+    private applySupersede;
+    private linkEntities;
+    /**
+     * Normalize the SPO slots of extracted triples through the same write entry as fact content.
+     *
+     * The triples are DERIVED (from an already-normalized content string, in `add`/`update`), but a
+     * tokenizer is free to hand back a half code unit, and a future truncation rule could split a
+     * surrogate pair — so the derived rows cross the same entry instead of trusting the producer.
+     */
+    private normalizeTriples;
+    private insertTriples;
+    private getRow;
+    private entityNames;
+    private entityBags;
+    private loadTexts;
+    /**
+     * Summary projection. `trust_score` follows the R11 display rule: the EFFECTIVE
+     * (decayed) value for active facts and the STORED one for non-active rows;
+     * `remaining_days` is null for pinned / non-active rows (spec §6) so it can never
+     * go negative.
+     */
+    private toSummary;
+    private toDetail;
+}

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

@@ -0,0 +1,43 @@
+import type { BrowseEntry, BrowseListing, SourceClassification, SourceKind } from '../../mem-contract/index.js';
+import { type IngestLimits } from './ingest_guard.js';
+/**
+ * The shapes come from the CONTRACT, and core re-exports them for its own callers.
+ *
+ * The engine owns the behaviour, but the browser half needs the types WITHOUT the engine, so the
+ * contract owns them (see `SourceClassification` / `BrowseListing` there). No hand-mirror left to
+ * drift, which is why the re-export below exists: `export type { X } from '…'` alone does NOT put `X`
+ * in this module's scope, so the separate `import type` above is what the rest of this file uses.
+ */
+export type { BrowseEntry, BrowseListing, SourceClassification, SourceKind };
+/** Split one source string the way `kb import` does: whitespace or comma separated. */
+export declare function splitSourceInput(raw: string): string[];
+/**
+ * Walk one directory for ingestable files: text formats plus PDF.
+ *
+ * Everything else is reported as SKIPPED rather than dropped silently — a directory of 200 files
+ * where 3 were ingested and 197 ignored used to look exactly like a directory of 3 files.
+ */
+export declare function listTextFiles(dir: string): {
+    files: string[];
+    skipped: string[];
+};
+/** Would ingestion take this file name? */
+export declare function isIngestableFile(name: string): boolean;
+/**
+ * Classify one source input without ingesting anything.
+ *
+ * The order matters: a URL wins outright, then anything that resolves on disk (several paths, a
+ * directory, a file), then a path-SHAPED input that does not resolve is `missing` (a typo, or a
+ * path outside the boundary — the reason says which), and only then is it pasted text. Long or
+ * many-token inputs skip the filesystem probes entirely: prose is not a path list, and a paragraph
+ * should not cost thousands of `stat` calls.
+ */
+export declare function classifySource(raw: string, limits: IngestLimits): SourceClassification;
+/**
+ * List one directory for the picker.
+ *
+ * `requested` empty ⇒ the first allowed root. Every requested path goes through
+ * {@link resolveLocalSource}, so the picker can never show (or hand back) a directory that
+ * ingestion would refuse; `parent` stops at a root for the same reason.
+ */
+export declare function browseDirectory(requested: string | undefined, limits: IngestLimits): BrowseListing;