@avantf/dsh-mem 0.7.0 → 0.8.0

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

@@ -0,0 +1,52 @@
+/**
+ * Structured relations a WRITE declares (docs/STRUCTURED_RELATIONS.md §2).
+ *
+ * The caller states `(subject, predicate, object)` — this module turns that statement into the same
+ * `RelationCandidate` shape the extraction path produces, or refuses it with a message that names the
+ * offending slot. It is deliberately a separate module from `relations/extract.ts`: nothing here
+ * GUESSES, so nothing here may silently drop. An explicit relation that cannot be written is a
+ * caller mistake (a refusal), not an extraction miss (a drop sample).
+ *
+ * The gates, in the order they run:
+ *
+ *  1. **layer.** `kind: "note"` only (§一: the graph expresses stable facts; a journal entry is an
+ *     episode). The check lives HERE and runs before the write, so the CLI, the tool boundary, the
+ *     Remote gateway and any embedder get the same refusal.
+ *  2. **shape.** Each slot must be non-blank, single-line and bounded, and both entity slots must
+ *     pass `relations/name-quality.ts` — the same gate the extractor's edges pass. A name gate that
+ *     only applied to extracted edges would let the one path a CALLER controls put a clause in the
+ *     graph.
+ *  3. **self-relation** after alias resolution (§二). `老张 管理 张伟` with `老张 → 张伟` is not an
+ *     edge, and for an explicit statement the caller must be told rather than silently ignored.
+ *
+ * What is deliberately NOT here: the confidence floor and the statement test
+ * (`relations/statement.ts`). Those gate a GUESS. An explicit relation carries confidence 1 and the
+ * `explicit` source, which is what `relations/confidence.ts#evaluateRelation` reads to skip them.
+ *
+ * @module store/explicit_relations
+ */
+import { type MemoryKind, type RelationInput } from '../../mem-contract/index.js';
+import type { Db } from '../db/port.js';
+import { type RelationCandidate } from '../relations/index.js';
+/**
+ * The refusal for `journal` + `relations` (§一/§二).
+ *
+ * It names the way out, for the same reason {@link JOURNAL_NEEDS_EVENT_DATE} does: the caller has
+ * already decided the relation is worth keeping, and the only thing missing is which layer to put it
+ * in.
+ */
+export declare const RELATIONS_NEED_NOTE: string;
+/**
+ * Validate + normalize the `relations` of one write, or refuse.
+ *
+ * Returns `[]` when nothing was given (an omitted or EMPTY array is "no relations", §二), so the
+ * caller can treat the result uniformly. The thrown messages are caller-facing: they name the
+ * layer, the index and the slot, because a model or an operator has to be able to fix the call.
+ *
+ * @param db - the store's connection (needed only for the read-only alias resolution of §二's
+ *   self-relation rule).
+ * @param kind - the layer the revision will actually carry; the caller resolves it (for `update`
+ *   that is the replaced row's kind when the request omits one).
+ * @param relations - what the caller passed, if anything.
+ */
+export declare function explicitRelationTriples(db: Db, kind: MemoryKind, relations: readonly RelationInput[] | undefined): RelationCandidate[];

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

@@ -4,7 +4,7 @@
  *
  * RESTORE IS NOT IMPORT. `import` / `merge` (see `facts_io.ts`) are CONTENT-IDENTITY UNIONS: new
  * rows get new ids, only ACTIVE facts travel, and every value the document carries beyond
- * category/ttl/sources/validity is counted as dropped. Restore is the opposite promise — "put this
+ * kind/ttl/sources/validity is counted as dropped. Restore is the opposite promise — "put this
  * library back exactly as it was" — which is only answerable if the target is EMPTY:
  *
  *   - `facts` is written DIRECTLY, one transaction, keeping `fact_id`, status, timestamps,
@@ -41,6 +41,14 @@
  * Zero would make every restored fact decay by the host's whole clock in one settlement; the current
  * clock is the "no decay has happened yet" baseline, which is what a fresh restore means.
  *
+ * V5 DECLARED RELATIONS ARE RESTORED, AS EDGES. A note's `relations` (the relations a caller stated,
+ * `source: 'explicit'`) are written into `edges` inside the same transaction as the fact. They are
+ * the one part of the graph the entity sweep cannot re-derive (that pass re-creates extracted edges
+ * and PRESERVES explicit ones), so treating them like the rest of the derived state would lose them.
+ * The field is counted in `metadata_missing` for notes only: a journal refuses relations by contract,
+ * so an absent key on a journal row states the truth instead of a loss. A journal row that DOES carry
+ * them is refused outright — such a row cannot be represented in this schema.
+ *
  * @module store/facts_restore
  */
 import type { FactsExportDocument } from '../facts_io.js';
@@ -56,7 +64,7 @@ export declare const RESTORE_VECTOR_HINT: string;
  * rather than trust). A field counts as missing when the document does not carry the key at all —
  * `null` is a value the document states ("unknown"), not an absence.
  */
-export declare const RESTORE_METADATA_FIELDS: readonly ["category", "created_at", "updated_at", "trust_score", "pinned", "pinned_at", "assert_count", "helpful_count", "last_reinforced_at", "ttl_days", "valid_from", "valid_to", "supersedes_source_id", "archive", "sources", "settle_clock", "bonus_count", "bonus_window_at", "retrieval_count", "last_retrieved_at", "mirror_source", "mirror_target", "entities_version", "conflict_checked"];
+export declare const RESTORE_METADATA_FIELDS: readonly ["kind", "title", "created_at", "updated_at", "trust_score", "pinned", "pinned_at", "assert_count", "helpful_count", "last_reinforced_at", "ttl_days", "valid_from", "valid_to", "supersedes_source_id", "archive", "sources", "settle_clock", "bonus_count", "bonus_window_at", "retrieval_count", "last_retrieved_at", "mirror_source", "mirror_target", "entities_version", "conflict_checked", "relations"];
 export type RestoreMetadataField = (typeof RESTORE_METADATA_FIELDS)[number];
 /** Per-field count of facts whose document did not carry that field. */
 export type RestoreMetadataMissing = Record<RestoreMetadataField, number>;

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

@@ -99,7 +99,10 @@ export type FloorLeg = 'semantic' | 'fts' | 'jaccard';
  *    that cannot produce terms is not graded at all, and one that produces a single term (every
  *    3-char CJK query, and every 2-char one through the substring fallback) is already graded
  *    against that one term by the reachability clamp.
- *  - jaccard **0.15** (positive — the previous `0` was the ungated hole this closes). The metric was
+ *  - jaccard **0.15** (positive — the previous `0` was the ungated hole this closes). This is the
+ *    LOWER BOUND of the entity leg's evidence bar: the leg also applies a per-candidate anchor-rarity
+ *    bar in the same metric unit (`entityEvidenceFloor`, 2026-10-21), so "relaxed" cannot re-admit a
+ *    generic anchor's wide-fact tail — the structural relation is not a relevance threshold. The metric was
  *    recalibrated on 2026-10-04 (`store/entity_leg.ts`): the leg still scores a Jaccard ratio, but
  *    over the query's ANCHOR entities and with the fact's extra-entity term SATURATED at
  *    `ENTITY_UNION_CAP`. 0.15 on that unit means "shares at least one discriminative entity" for any

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

@@ -0,0 +1,146 @@
+/**
+ * The memory adapter for the shared `@avantf/graph-recall` port
+ * (docs/GRAPH_RECALL_LIBRARY.md §6, Phase 3b).
+ *
+ * WHY THIS FILE EXISTS. The library owns the traversal algorithms (one hop, reverse, two hops, AND,
+ * neighbours) and knows nothing about SQLite; memory owns the storage and therefore must supply a
+ * {@link GraphReader}. That is this class and nothing more: it maps `edges` + `entities` +
+ * `predicates` rows onto `GraphEdge` / `GraphNode` and owns EVERY filtering decision the library
+ * refuses to guess.
+ *
+ * THE DIVISION OF LABOUR, spelled out because it is the whole point of Phase 3:
+ *
+ *  - **The reader filters.** Only `facts.status = 'active'` rows are edges of the live graph; a
+ *    `kind`, `source` (`fact_sources.ref`) or `time` filter is applied inside the SQL, before any
+ *    `LIMIT`, exactly like the retrieval legs do it (`store/memory.ts#SearchInput`). A superseded
+ *    revision's edges are deleted by the write path, so "archived" here means a row whose status
+ *    moved after the fact was written — the contradiction/supersede paths — and it must not be
+ *    walkable.
+ *  - **The reader normalizes names.** `resolveNode` follows `relations/normalize.ts`'s order
+ *    (explicit alias, then exact name, then — last, so a name never shadows an id — the numeric
+ *    `entity_id`); `resolvePredicate` follows the same alias-then-name order. Walkers call
+ *    `resolvePredicate` before reading, so an alias (`负责`) and its canonical (`管理`) are one hop
+ *    predicate, never two.
+ *  - **Direction is the STORED one.** `outgoing` reads `subject_id = ?`, `incoming` reads
+ *    `object_id = ?`, and the adapter never flips endpoints: a predicate registered as `inverse` was
+ *    already stored in its canonical orientation by the write path (`db/graph.ts`), which is what
+ *    lets every walker read edges left to right. The ONE exception is a SYMMETRIC relation (`合作`):
+ *    it is stored once, in the order the sentence used, and a predicate-filtered read anchors on
+ *    either endpoint, so both ends of the relation answer (see `read`).
+ *  - **Evidence is the fact.** `GraphEdge.factId` is `edges.fact_id`, so a `RelationPath.evidence`
+ *    points at the row a caller can open (`mem_admin detail`), not at an edge id only this adapter
+ *    understands.
+ *  - **The vocabulary is the adapter's too.** `entitiesIn` / `predicatesIn` (Phase 4) are the
+ *    `RelationVocabulary` port the planner reads: which known surfaces occur where in a query. Those
+ *    lookups belong here because they are the same normalization (`entity_aliases` first, then
+ *    `entities.name`; alias-then-canonical for predicates) the walks use.
+ *
+ * WHAT IS DELIBERATELY ABSENT: no query planner (that is `store/relation_planner.ts`), no answer
+ * generation, no new action, and no change to `titles`. `MemoryStore` builds one of these per search
+ * for the relation stage — the class stays an adapter with no policy of its own — and it is still not
+ * exported from the engine's front door, the same status `db/graph.ts` has: reachable by module path,
+ * not a published promise.
+ *
+ * @module store/graph_reader
+ */
+import type { GraphEdge, GraphNode, GraphReader } from '../../graph-recall/index.js';
+import type { MemoryKind, TimeFilter } from '../../mem-contract/index.js';
+import type { Db } from '../db/port.js';
+import { type SurfaceMatch } from './relation_planner.js';
+/**
+ * Hard ceiling on one read's `LIMIT`.
+ *
+ * The library over-fetches (`limit × 5`, capped at its own `MAX_SCAN = 500`) and never calls a read
+ * without a limit, so this is the bound an omitted `limit` falls back to rather than a second policy:
+ * an unbounded `SELECT * FROM edges WHERE subject_id = ?` on a hub entity would be a table scan, and
+ * "at most `limit`" is the contract's promise, not "all of them".
+ */
+export declare const MAX_GRAPH_EDGE_READ = 500;
+/**
+ * Which facts a reader may walk.
+ *
+ * Every field is ANDed with the others and with `status = 'active'`; an omitted field filters
+ * nothing. An EMPTY list is not "no restriction" — a kind/source allowlist that names nothing
+ * permits nothing, and silently widening it to the whole corpus is the failure mode a filter exists
+ * to prevent.
+ */
+export interface MemoryGraphFilter {
+    /** `facts.kind` values to keep (the two memory layers, see `store/kinds.ts`). */
+    kinds?: readonly MemoryKind[];
+    /**
+     * `fact_sources.ref` values to keep — the same `source` axis `mem_recall.search` exposes (P-08).
+     *
+     * Note the write-side spelling: `mem_remember source_ref: 'session:abc'` records kind `session`,
+     * ref `abc` (`dao/fact_sources.ts#classifySourceRef`), and `ref` is what this filter compares —
+     * the same value `mem_recall`'s `source=` matches.
+     */
+    sources?: readonly string[];
+    /**
+     * The caller's explicit time filter, on `facts` (`store/time_filter.ts`'s normalizer, i.e. the very
+     * same grammar and axes `mem_recall` uses: `created` / `updated` / `event`).
+     */
+    time?: TimeFilter;
+}
+/**
+ * A read-only {@link GraphReader} over a memory database.
+ *
+ * Construct one per query — it holds a filter and a connection, no mutable state, so concurrent
+ * readers on one connection cannot interfere — and hand it to the `@avantf/graph-recall` operators:
+ *
+ * ```ts
+ * const reader = new MemoryGraphReader(db, { kinds: ['note'] })
+ * const zhang = reader.resolveNode('张伟')
+ * if (zhang !== null) {
+ *   const { paths } = twoHop(reader, zhang, '管理')
+ *   for (const path of paths) console.log(path.evidence) // fact ids
+ * }
+ * ```
+ */
+export declare class MemoryGraphReader implements GraphReader {
+    private readonly db;
+    /** The normalized time range, parsed ONCE in the constructor so a bad `time` fails fast. */
+    private readonly timeRange;
+    /** `undefined` = the axis is not filtered; `[]` = an allowlist that names nothing (matches nothing). */
+    private readonly kinds;
+    private readonly sources;
+    constructor(db: Db, filter?: MemoryGraphFilter);
+    resolveNode(ref: string): GraphNode | null;
+    resolvePredicate(ref: string): string | null;
+    /**
+     * The entity surfaces occurring in `text` — the planner's vocabulary port (`store/relation_planner.ts`).
+     *
+     * Only entities the graph can actually walk are reported: an entity with no `edges` row can never
+     * answer a relation question, so including it would let a plan form and then come back empty (a
+     * fuzzy fallback with extra work), and scanning the whole `entities` table on every search would
+     * pay for names the relation stage can never use. The alias rows are narrowed the same way.
+     *
+     * Filtering (kind/source/time) is deliberately NOT applied to this lookup: the vocabulary answers
+     * "is this name an entity at all", while the paths are filtered by the edge SQL. A name whose only
+     * edges are outside the caller's window still forms a plan — and then yields no path, which is the
+     * documented fallback to fuzzy.
+     */
+    entitiesIn(text: string): SurfaceMatch[];
+    /** The predicate surfaces occurring in `text` (canonical names and aliases) — same port as above. */
+    predicatesIn(text: string): SurfaceMatch[];
+    outgoing(node: GraphNode, predicate?: string, limit?: number): GraphEdge[];
+    incoming(node: GraphNode, predicate?: string, limit?: number): GraphEdge[];
+    edgesForFact(factId: string | number): GraphEdge[];
+    /** One alias-or-canonical-name lookup; `undefined` when the predicate is not in the vocabulary. */
+    private predicateRow;
+    /**
+     * Shared read behind {@link outgoing} / {@link incoming} / {@link edgesForFact}.
+     *
+     * `anchorColumn` is the ONE difference between the three reads (`subject_id`, `object_id`,
+     * `fact_id`), which is why they cannot drift apart in their filters: active status, kind, source,
+     * time and the page bound are appended in exactly one place.
+     */
+    private read;
+    /**
+     * Build one bounded, filtered edge read.
+     *
+     * Bind order is the SQL's own: kind list, source list, time bounds, anchor, predicate, limit.
+     * `ORDER BY e.edge_id` is insertion order — stable across calls, which is what the port asks for
+     * ("the library sorts by confidence/hops/recency itself").
+     */
+    private edgeQuery;
+}

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

@@ -4,7 +4,7 @@
  * `MemoryStore.search` and `KnowledgeStore.search` used to carry parallel copies of this flow
  * (~80 lines each: limit normalization → weights → over-fetch → leg cap → fuse → live filter →
  * slice → output budget → health event). The legs themselves are legitimately store-specific —
- * different tables, different filters (`category` vs `domain`/`source`), and only memory has the
+ * different tables, different filters (`kind` vs `domain`/`source`), and only memory has the
  * HRR probe — but the ORCHESTRATION is one algorithm, and two copies of it drifted:
  *
  *   - the `NaN` limit guard existed only in memory, so a non-finite limit reached knowledge's SQL
@@ -25,6 +25,7 @@
  */
 import { type Config, type FloorProfile, type RecallResult, type RetrievalFloorDrops, type RetrievalFloors } from '../../mem-contract/index.js';
 import { type BudgetInput, type Hit, type SemanticBackend } from '../../mem-retrieval/index.js';
+import type { Awaitable } from '../interfaces/common.js';
 import { type FloorLeg } from './floors.js';
 /**
  * A retrieval input the CALLER got wrong, as opposed to a backend that failed at runtime.
@@ -107,8 +108,8 @@ export interface HybridContext {
 }
 /** What a store supplies. Generic in `H`, the caller-facing hit shape. */
 export interface HybridDeps<H> {
-    /** Which health-event kind this search records. */
-    kind: 'memory' | 'knowledge';
+    /** Which health-event bucket this search records (`retrieval.by_kind`). */
+    kind: 'memory';
     config: Config;
     semantic: SemanticBackend;
     /**
@@ -118,10 +119,10 @@ export interface HybridDeps<H> {
      * body, before the array is returned.
      */
     legs(ctx: HybridContext): Promise<readonly (HybridLeg | Promise<HybridLeg>)[]>;
-    /** Text for the fused ids: the live filter and the hit bodies. */
-    texts(ids: number[]): Map<number, string>;
+    /** Text for the fused ids: the live filter and the hit bodies (a repository read — DB-2). */
+    texts(ids: number[]): Awaitable<Map<number, string>>;
     /** Build the caller-facing hits from the ranked, live, already-sliced ids. */
-    hits(ranked: readonly Hit[], texts: Map<number, string>): H[];
+    hits(ranked: readonly Hit[], texts: Map<number, string>): Awaitable<H[]>;
     /**
      * Called with the hits the caller ACTUALLY receives — after the output budget, not before it.
      *
@@ -130,7 +131,7 @@ export interface HybridDeps<H> {
      * dropped, i.e. rewarding facts the caller never saw; the cross-store path had already learned
      * that lesson (R5/R21) and the single-store path had not.
      */
-    onReturn?(kept: readonly Budgeted<H>[]): void;
+    onReturn?(kept: readonly Budgeted<H>[]): Awaitable<void>;
 }
 /** One search request, before resolution. */
 export interface HybridPlan {
@@ -168,6 +169,20 @@ export interface HybridPlan {
      * too (relaxing a leg that dropped nothing admits no candidate; it only misreports `floors`).
      */
     relaxLegs?: readonly FloorLeg[];
+    /**
+     * Overrides `retriever.min_score` for this search (`0` = off). The UNIFIED cross-store entry
+     * (`runtime.retrieve`) passes `0` here and applies the score floor ONCE, after the merged pool has
+     * been normalized, because a per-store floor runs on a different scale in each store (DESIGN §7).
+     * A direct store search leaves this absent and keeps the configured value.
+     */
+    minScore?: number;
+    /**
+     * READ-ONLY probe mode (`AvantfRuntime.wouldFind`, DESIGN §12): no model warm, no leg-capped
+     * counters, no retrieval event and no `onReturn` reinforcement. The legs themselves are the same
+     * ones a user query runs, because the probe's answer must be exactly "would retrieval return a
+     * hit?"; only the SIDE EFFECTS are suppressed.
+     */
+    probe?: boolean;
     /**
      * Emit a health event for this search (default true). The cross-store router sets it false: it
      * fuses both stores into ONE user-facing query and records a single `kind: 'cross'` event, so
@@ -196,6 +211,24 @@ export interface HybridResult<H> {
     floors: RetrievalFloors;
     /** How many candidates each leg dropped below its floor. */
     dropped_by_floor: RetrievalFloorDrops;
+    /**
+     * Candidates the FUSED-score floor (`retriever.min_score`) removed after the live filter.
+     *
+     * Deliberately a scalar, not a `RetrievalFloorDrops` member: a score drop happens AFTER all legs
+     * have been fused, so there is no leg to attribute it to. Folding it into the per-leg structure
+     * would also make the retry rule and the panel's "the floors removed N" claim describe a rule that
+     * did not remove the candidate.
+     *
+     * Absent when nothing was dropped (including whenever `min_score` is off). The count covers every
+     * live candidate below the threshold, including ones the `limit` slice would have discarded anyway,
+     * because the threshold is applied before the slice. It is the CHOSEN pass's count: when
+     * {@link HybridResult.relaxed} is true it describes the relaxed pass, like `floors`.
+     *
+     * The UNIFIED entry (`runtime.retrieve`) passes `minScore: 0` and applies the floor once, after the
+     * merged-pool normalization (`router.crossQuery`), so this field is absent on that path; the
+     * router's own `dropped_by_score` is the cross-store count (DESIGN §7).
+     */
+    dropped_by_score?: number;
     /**
      * The strict pass returned nothing while having dropped candidates, and ONE relaxed pass supplied
      * these hits — `floors` are that pass's values. An explicit `floors: 'loose'` request does NOT set
@@ -233,11 +266,15 @@ export declare function hybridSearch<H extends BudgetInput>(deps: HybridDeps<H>,
 /**
  * The search-entry fields `MemoryStore.search` and `KnowledgeStore.search` hand to the orchestrator.
  * Both stores' option types (`SearchInput` / `KnowledgeSearchOptions`) satisfy this structurally;
- * everything else on them (`category` / `source` / `domain` / `includeHrr` / `track` / `onResult`) is
+ * everything else on them (`kind` / `source` / `domain` / `includeHrr` / `track` / `onResult`) is
  * leg- or domain-specific and stays at the store.
  */
 export interface HybridSearchEntryFields {
     limit?: number;
+    /** See {@link HybridPlan.minScore}. `0` = the caller applies the score floor itself. */
+    minScore?: number;
+    /** See {@link HybridPlan.probe}: read-only, no side effects. */
+    probe?: boolean;
     /**
      * Knowledge only: overrides the config-derived pool size. Memory's `SearchInput` has no such field
      * and leaves the plan key absent (see {@link runHybridSearch}).
@@ -274,9 +311,9 @@ export declare function runHybridSearch<H extends BudgetInput>(deps: HybridDeps<
  */
 export declare function hybridPlanOf(query: string, fields: HybridSearchEntryFields | undefined): HybridPlan;
 /**
- * Build a store's {@link HybridDeps} — the ONE construction site for the contract fields both stores
- * share (`kind` / `config` / `semantic` / `legs` / `texts` / `hits` / `onReturn`). The per-store half
- * is `parts`; the stores used to spell the whole object out twice, so a new required `HybridDeps`
- * field was a change to remember in two places.
+ * Build a store's {@link HybridDeps} — the ONE construction site for the fields every caller shares
+ * (`kind` / `config` / `semantic` / `legs` / `texts` / `hits` / `onReturn`). The per-caller half is
+ * `parts`; a store built on these legs passes its own `kind` and parts, so a new required
+ * `HybridDeps` field does not have to be remembered in more than one place.
  */
-export declare function makeHybridDeps<H>(kind: 'memory' | 'knowledge', config: Config, semantic: SemanticBackend, parts: Pick<HybridDeps<H>, 'legs' | 'texts' | 'hits' | 'onReturn'>): HybridDeps<H>;
+export declare function makeHybridDeps<H>(kind: 'memory', config: Config, semantic: SemanticBackend, parts: Pick<HybridDeps<H>, 'legs' | 'texts' | 'hits' | 'onReturn'>): HybridDeps<H>;

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

@@ -0,0 +1,47 @@
+/**
+ * The memory LAYERS at the WRITE boundary (JOURNAL_NOTES_REDESIGN N1/N6/N7).
+ *
+ * `kind` replaced the eight-value `category` vocabulary: a fact is either a `journal` entry (what was
+ * done / talked about / thought about, anchored by an event date) or a `note` (a stable fact,
+ * preference, decision or pitfall). Three layers agree, each with a distinct job:
+ *
+ *  1. the contract's `z.enum(MEMORY_KINDS)` — the MODEL cannot even phrase an unknown value;
+ *  2. {@link kindOrThrow} — the ENGINE refuses one, so the CLI, the UI, an import and an embedder
+ *     (none of which pass through the tool schema) get the same answer;
+ *  3. `facts.kind`'s CHECK constraint (the base DDL) — the DATABASE refuses one, which is what makes
+ *     the rule hold for a writer this build does not control (an older process sharing the file).
+ *
+ * There is no lookup table any more (the old `categories` table is dropped by migration 13): two
+ * values do not need to be stored as data, and the schema test would have to keep them in step.
+ *
+ * @module store/kinds
+ */
+import { type MemoryKind } from '../../mem-contract/index.js';
+/** The EPISODIC layer: one row per episode, and it cannot exist without its event time. */
+export declare const JOURNAL_KIND: MemoryKind;
+/** The SEMANTIC layer — also what an omitted `kind` means on a new row (CLI / import / base). */
+export declare const NOTE_KIND: MemoryKind;
+/** Whether `value` is one of the two layers (the engine's own guard). */
+export declare function isMemoryKind(value: string): value is MemoryKind;
+/**
+ * Validate a caller's `kind`, or refuse with the allowed set.
+ *
+ * Whitespace/case are NOT "helpfully" accepted: `kind` is an identity (the column's CHECK compares it
+ * verbatim), and silently folding `Journal` into `journal` would make the stored value depend on which
+ * layer normalized it.
+ */
+export declare function kindOrThrow(value: string): MemoryKind;
+/**
+ * Map ANY historical value onto the two layers. Used where the value is not a fresh caller choice but
+ * data written by an older build (a snapshot restore, an old export, a pre-migration database), so
+ * refusing it would refuse the whole file over a label.
+ *
+ * `worklog` (the one episodic value in the published 16-value set, and in the eight-value experiment)
+ * is `journal`; every other value is `note` — the old vocabularies were topic taxonomies, and "the
+ * topic of a fact" says nothing about whether it is an episode.
+ */
+export declare function mapLegacyKind(value: unknown): MemoryKind;
+/** `true` when this layer cannot be written without an event date (N6). */
+export declare function requiresEventDate(kind: string): boolean;
+/** The refusal text for a `journal` write without `event_date` — one sentence, with the way out. */
+export declare const JOURNAL_NEEDS_EVENT_DATE: string;

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

@@ -40,7 +40,7 @@
  */
 import { type FloorLeg } from './floors.js';
 import { type HybridContext, type HybridLeg } from './hybrid.js';
-import { type FtsTokenizer } from '../db/tokenizer.js';
+import type { Awaitable } from '../interfaces/common.js';
 /**
  * The legs {@link LegRunner.scored} may wrap: those whose raw score has an absolute scale a floor
  * can cut. `semantic` is excluded on purpose — it shares `applyScoreFloor` but must not carry the
@@ -94,44 +94,39 @@ export declare function makeLegRunner(ctx: Pick<HybridContext, 'legCap'>): LegRu
 /** The per-store pieces of the FTS leg — see {@link ftsLeg}. `Scope` is opaque to the flow. */
 export interface FtsLegOptions<Scope> {
     query: string;
-    /** The per-leg row cap (the store's `legCap`), handed to whichever DAO statement runs. */
+    /** The per-leg row cap (the store's `legCap`), handed to whichever backend statement runs. */
     cap: number;
-    /** The store's scope shape (`{category, source}` / `{domain, source}`), passed straight through. */
+    /** The store's scope shape (`{kind, source}` / `{domain, source}`), passed straight through. */
     scope: Scope;
-    /** The table's own tokenizer, for the `MATCH` build (`buildFtsQuery`). */
-    tokenizer: FtsTokenizer;
-    /** The FTS `MATCH` statement; its `rank` is bm25 (negative = better). */
-    search: (ftsQuery: string, scope: Scope, limit: number) => readonly {
-        id: number;
-        rank: number;
-    }[];
-    /** The short-query LIKE statement; its `rank` counts the terms the row contains (higher = better). */
-    substringSearch: (terms: readonly string[], scope: Scope, limit: number) => readonly {
+    /**
+     * The store's lexical search, handed the CALLER'S QUERY.
+     *
+     * The backend decides how to express it (a full-text `MATCH`, or the short-query substring
+     * fallback when the index cannot express the text at all) and normalizes its own rank convention
+     * so `rank` is always HIGHER IS BETTER. That is the DB-3 boundary: neither the tokenizer nor
+     * bm25's sign crosses into the store.
+     */
+    search: (query: string, scope: Scope, limit: number) => Awaitable<readonly {
         id: number;
         rank: number;
-    }[];
+    }[]>;
 }
 /**
  * The FTS leg, shared by `MemoryStore.ftsPath` and `KnowledgeStore.ftsPath` (§4.6.1).
  *
- * The two were line-for-line the same flow — `buildFtsQuery` → the `MATCH` statement with NEGATED
- * bm25, else `substringTerms` → the LIKE statement with `rank` — differing only in the DAO and the
- * order its scope parameters bind. Both conventions are load-bearing and preserved verbatim:
+ * The two were line-for-line the same flow — build the index expression, run it, map hits to scores
+ * — differing only in the DAO and the order its scope parameters bind. What stays here is the shape
+ * both flows share: every hit becomes a score, and the leg is a `Map` in the backend's own order.
  *
- *  - **bm25 is negative** (more negative = better match), so the `MATCH` branch negates it and higher
- *    stays better everywhere downstream;
- *  - **the LIKE `rank`** already counts contained terms, so it is used as-is, keeping the two branches
- *    on the same "higher = better" scale;
- *  - **an empty term list returns the empty map** (`substringTerms` yields none for a query with no
- *    3-char run) — the leg is empty by construction, not by a query that matched nothing.
+ * THE SHORT-QUERY FALLBACK moved DOWN into the backend in DB-3. `buildFtsQuery` returning `null`
+ * (a 2-char CJK query the trigram vocabulary cannot express) used to leave this leg empty by
+ * construction; the SQLite adapter now answers that shape with the bounded substring predicate
+ * itself, on the same "higher is better" scale, so the store has one call instead of a branch.
  *
- * THE SHORT-QUERY FALLBACK. `buildFtsQuery` returning `null` means the query carries no term the
- * trigram index can express (measured: every term in the FTS table is 3 characters), which used to
- * leave this leg empty by construction — the 2-char CJK shape. `substringTerms` is the one finer
- * predicate the FTS5 trigram TABLE still answers (`LIKE '%…%'`), bounded by `cap`; the accuracy guard
- * is the per-row term floor in `applyTermFloor`, which requires the row to CONTAIN the run.
+ * A backend that matches nothing returns an empty map — the leg is empty by construction, not by a
+ * query that matched nothing.
  */
-export declare function ftsLeg<Scope>(opts: FtsLegOptions<Scope>): Map<number, number>;
+export declare function ftsLeg<Scope>(opts: FtsLegOptions<Scope>): Promise<Map<number, number>>;
 /** The per-store pieces of the semantic leg — see {@link semanticLeg}. */
 export interface SemanticLegOptions {
     query: string;
@@ -155,7 +150,7 @@ export interface SemanticLegOptions {
      * short-circuit (no lookup runs at all). A returned set is the allow-list; the flow still maps the
      * pool in ITS order, so ids/scores/insertion order are the vstore's.
      */
-    filterTopk: (ids: readonly number[]) => ReadonlySet<number> | undefined;
+    filterTopk: (ids: readonly number[]) => Awaitable<ReadonlySet<number> | undefined>;
 }
 /**
  * The semantic leg, shared by `MemoryStore.semanticPath` and `KnowledgeStore.semanticPath` (§4.6.2).