@avantf/dsh-mem 0.6.4 → 0.8.0

package/lib/engine/mem-contract/types.d.ts

@@ -1,6 +1,55 @@
 /** Shared domain types for avantf-mem. Single source of truth in @avantf/mem-contract. */
-export declare const CATEGORY_VALUES: readonly ["user_pref", "user_env", "project", "tool", "general"];
-export type FactCategory = (typeof CATEGORY_VALUES)[number] | string;
+/**
+ * The memory has TWO layers, and `kind` says which one a fact belongs to
+ * (JOURNAL_NOTES_REDESIGN N1/N2).
+ *
+ *  - `journal` is EPISODIC: what was done / talked about / thought about, one entry per episode,
+ *    anchored by the caller's `event_date`. A journal row without an event date cannot answer
+ *    "what did I do yesterday", so the write path refuses one.
+ *  - `note` is SEMANTIC: a stable fact, preference, constraint, decision or pitfall that is worth
+ *    recalling without knowing when it was learned.
+ *
+ * This replaces the eight-value `category` vocabulary (and its `categories` lookup table): the model
+ * no longer classifies by topic, it picks a layer. The set lives here because four surfaces read it —
+ * `mem_remember`'s schema (required, enum), `mem_recall`/`mem_admin`'s filters, the store's write
+ * guard and the one migration that maps the old 16 free-form values onto it.
+ */
+export declare const MEMORY_KINDS: readonly ["journal", "note"];
+export type MemoryKind = (typeof MEMORY_KINDS)[number];
+/**
+ * What each layer is FOR — the text the tool schema and the prompt section show.
+ *
+ * Spelled once beside the vocabulary so a caller reading `mem_remember`'s parameter help and one
+ * reading `mem_recall`'s filter help see the same two meanings.
+ */
+export declare const MEMORY_KIND_DESCRIPTIONS: Readonly<Record<MemoryKind, string>>;
+/**
+ * The three time AXES a `mem_recall` call may filter on (TIME_SEARCH_AND_CATEGORIES D1).
+ *
+ * `created` = when the row was written, `updated` = when it was last modified, `event` = when the
+ * fact was TRUE (the caller's `event_date`, stored in `valid_from`). The axes never fall back into
+ * one another: a fact with no event time does not participate in an `event` filter, and a row that
+ * was never updated does not participate in an `updated` one (D3 in the implementation doc's §3.1).
+ *
+ * Declared here (not in `tools.ts`) because both the zod schema and the engine's normalizer read it:
+ * one list, so a fourth axis cannot reach the tool surface without reaching the SQL.
+ */
+export declare const TIME_FIELDS: readonly ["created", "updated", "event"];
+export type TimeField = (typeof TIME_FIELDS)[number];
+/**
+ * One explicit time filter — the shape `mem_recall.search`/`titles` accept on the wire.
+ *
+ * `field` is required (D1). Bounds: `on` (a whole day, or one minute when a time is given) XOR
+ * `from`/`to` (half-open range, `to` exclusive). Minute precision throughout (D3) — see
+ * `@avantf/mem`'s `store/time_filter.ts` for the normalization the engine applies.
+ */
+export interface TimeFilter {
+    field: TimeField;
+    on?: string;
+    from?: string;
+    to?: string;
+    timezone?: string;
+}
 /**
  * The fact statuses a caller may filter by, as the ONE list every surface reads: the tool schema's
  * `z.enum`, the derived MCP inputSchema and DSH parameter spec, and the CLI's `--status` flag (which
@@ -8,10 +57,34 @@ export type FactCategory = (typeof CATEGORY_VALUES)[number] | string;
  */
 export declare const FACT_STATUSES: readonly ["active", "archived"];
 export type FactStatus = (typeof FACT_STATUSES)[number];
+/**
+ * The status FILTER vocabulary: a fact-status set plus `all`.
+ *
+ * The two filter surfaces that accept it (`mem_admin export` and `mem_recall titles`) need
+ * "either status", while a fact VIEW can only ever carry one of {@link FACT_STATUSES}. Declared here
+ * so the two filters cannot drift into two spellings of "all".
+ */
+export declare const STATUS_FILTERS: readonly ["active", "archived", "all"];
+export type StatusFilter = (typeof STATUS_FILTERS)[number];
+/**
+ * The longest title a write may carry, in characters (contract, engine and every surface agree).
+ *
+ * 120, the upper end of the range the design allows: a title is a human handle for a journal entry
+ * ("which transaction was this"), not prose, and the cap is what keeps it from becoming one. The
+ * SEARCH query shares the bound because it is compared against the stored title with `=`/`LIKE`.
+ */
+export declare const TITLE_MAX_CHARS = 120;
 export interface FactSummary {
     fact_id: number;
     content: string;
-    category: string;
+    /**
+     * The short handle of a journal entry (see {@link TITLE_MAX_CHARS}); `null` on a legacy journal
+     * and on every note that was written without one. Display only — it never participates in the
+     * content relevance score.
+     */
+    title: string | null;
+    /** Which memory layer this fact belongs to (see {@link MEMORY_KINDS}). */
+    kind: MemoryKind;
     status: FactStatus;
     /**
      * Trust as of now: the decayed value for an ACTIVE fact, the stored value for a
@@ -33,6 +106,20 @@ export interface FactTriple {
     obj: string;
     confidence: number;
 }
+/**
+ * One relation a CALLER stated on a note (`mem_remember.relations`), read back for the detail view
+ * (STRUCTURED_RELATIONS §2/§5).
+ *
+ * This is the EXPLICIT half of the graph resolved back to its stored names (after entity/predicate
+ * normalization) — the same three slots the write took. Extracted edges (`source: 'svo'`) are
+ * deliberately not part of this list: they are derivable from `content`, and mixing them in would
+ * make "what did the caller state" unanswerable. A journal has none by construction (note-only).
+ */
+export interface FactRelation {
+    subject: string;
+    predicate: string;
+    object: string;
+}
 /**
  * The retention diagnostics on a fact view: the trust value, the active days left before the
  * trust clock forgets it, and the reinforcement counter.
@@ -54,6 +141,15 @@ export interface FactDetail extends FactSummary {
     supersedes_id: number | null;
     entities: string[];
     triples: FactTriple[];
+    /**
+     * The relations a CALLER stated on this note (`source: 'explicit'`), in insertion order.
+     *
+     * Empty for a note nobody declared relations for and for every journal (the layer refuses them).
+     * `update` REPLACES this set; an update that omits `relations` and lands on the same row leaves
+     * it untouched, while a changed content starts a new revision with no explicit edges of its own
+     * (STRUCTURED_RELATIONS §5).
+     */
+    relations: FactRelation[];
     /** Active-day clock value at the last settle. */
     settle_clock: number;
     pinned_at: string | null;
@@ -94,36 +190,25 @@ export interface FactSourceView {
     kind: 'session' | 'kb_doc' | 'tool' | 'manual';
     ref: string;
 }
-/** A single hit from hybrid retrieval over the merged candidate pool. */
+/** A single hit from hybrid retrieval over the memory corpus. */
 export interface RecallHit {
-    kind: 'fact' | 'doc_chunk';
+    /** The hit type. Only memory facts remain, so this is always `fact`. */
+    kind: 'fact';
     ref_id: number;
     text: string;
     score: number;
-    /**
-     * Knowledge-base taxonomy (`domain → source`) of a `doc_chunk`, taken from the
-     * `documents` row by the store that owns it. Both are null for memory facts.
-     *
-     * Carried as fields rather than re-parsed out of `source_ref`: either name may
-     * itself contain `:` (`domain:source:docId:idx`), so any split of `source_ref`
-     * is a guess. Filters must use these, and so must the UI.
-     */
-    domain: string | null;
-    source: string | null;
     source_ref: string;
     entities: string[];
     /**
      * When this hit was first recorded: a fact's revision chain keeps the ORIGINAL row's
      * `created_at` across a supersede (`mem_remember update`), so this is when the memory was
-     * first asserted, not when its current text was written (see `updated_at`). A doc_chunk
-     * carries its owning document's `created_at`.
+     * first asserted, not when its current text was written (see `updated_at`).
      */
     created_at: string;
     /**
      * When this row was last CHANGED — an edit, pin/unpin, reinforcement, archive or restore.
      * Retrieval and the daily settle deliberately do not write it, so it never means "last
-     * retrieved"; a copy can carry `null` on a legacy row. A doc_chunk carries its owning
-     * document's `updated_at` (re-ingest bumps it).
+     * retrieved"; a copy can carry `null` on a legacy row.
      */
     updated_at: string | null;
     /**
@@ -143,11 +228,10 @@ export interface RecallHit {
      */
     scores?: Record<string, RecallLegScore | null>;
     /**
-     * P-01: the FUSION output score for this hit, before any cross-store normalization.
+     * P-01: the FUSION output score for this hit, before the output budget reshapes the list.
      *
-     * `score` is what the surface ranks by and can be re-scaled downstream (`crossQuery` min-max
-     * normalizes over the merged pool), so a caller reasoning about "which leg carried this" needs
-     * the fusion value itself rather than a number that means a different thing per surface.
+     * `score` is what the surface ranks by, so a caller reasoning about "which leg carried this"
+     * needs the fusion value itself rather than the rounded number a surface prints.
      */
     final?: number;
     /**
@@ -157,7 +241,240 @@ export interface RecallHit {
      */
     valid_from?: string;
     valid_to?: string;
+    /**
+     * The fact's title, when it has one (journal entries normally do, notes usually do not).
+     *
+     * A DISPLAY field: it is serialized only when non-null (the same convention as `valid_from`) and
+     * it is deliberately not part of any retrieval score — title search is its own action
+     * (`mem_recall.titles`), and mixing the two score semantics is what that action exists to
+     * avoid.
+     */
+    title?: string;
+}
+/**
+ * One candidate of `mem_recall.titles` — a title match, NOT a content hit.
+ *
+ * Deliberately its own shape instead of {@link RecallHit}: `RecallHit.kind` means "the hit type"
+ * (`fact`), while this shape needs the memory LAYER (`journal`/`note`), and the identity field the
+ * caller acts on is `fact_id` (`RecallHit` calls it `ref_id`). Reusing the hit would make `kind`
+ * carry two meanings and would let the model mistake a title match for a content relevance score.
+ *
+ * There is NO `score` field on purpose (JOURNAL_TITLE_SEARCH §11.4): the ordering (exact title >
+ * prefix > matched terms > recency) is computed on the server, and a number exported here would be
+ * read as "how relevant the CONTENT is", which is `mem_recall.search`'s answer, not this one's.
+ */
+export interface TitleCandidate {
+    fact_id: number;
+    /** The row's CURRENT title — the handle to continue the transaction with. */
+    title: string;
+    /**
+     * The title text the query matched: normally `title`, and one of the aliases a CORRECTED
+     * transaction used to carry when the old handle is what matched (v17's controlled `retitle`).
+     *
+     * Always present, so a caller can compare the two without a special case: `matched_title !== title`
+     * means "this hit came from an old name" — the row is the same transaction, just renamed.
+     */
+    matched_title: string;
+    memory_kind: MemoryKind;
+    status: FactStatus;
+    created_at: string;
+    updated_at: string | null;
+    /** The fact's event time (`valid_from`), when it has one — the journal axis that tells two entries apart. */
+    event_date?: string;
+    /** The first characters of the content, for judging "same transaction or not"; absent when `include_excerpt` is false. */
+    excerpt?: string;
+}
+/** One page of an EXACT result — the envelope both exact surfaces report (RECALL_INTERFACE §3). */
+export interface ExactPageEnvelope {
+    /** How many facts matched the literal query (before paging). */
+    total: number;
+    /** The page's first row index (`0`-based). */
+    offset: number;
+    /** The page size that was applied (after the 50 cap). */
+    limit: number;
+    /** `offset + hits.length < total` — there is another page. */
+    truncated: boolean;
+}
+/** `mem_recall.search` when the literal (exact) pass matched: RAW hits, never floored (RECALL_INTERFACE §2.2/§5). */
+export type ExactSearchResult = ExactPageEnvelope & {
+    mode: 'exact';
+    hits: RecallHit[];
+};
+/**
+ * `mem_recall.search` when the caller gave a TIME WINDOW and no query (RECALL_INTERFACE §2.4).
+ *
+ * The window IS the question: no literal pass, no relation plan, no fuzzy legs. `hits` are the
+ * active facts inside the window, newest first along `time.field`, and `score` is the same constant
+ * 1 the exact page reports — there is no relevance number here to compare with anything.
+ */
+export type TimeSearchResult = ExactPageEnvelope & {
+    mode: 'time';
+    hits: RecallHit[];
+};
+/**
+ * `mem_recall.search` when no literal match existed: the hybrid retrieval, unchanged except that its
+ * knobs are the engine's fixed rules (`min_score = 0.5`, `topK = 5`) instead of caller parameters.
+ */
+export type FuzzySearchResult = RecallResult & {
+    mode: 'fuzzy';
+};
+/** One endpoint of a relation path — the STORED entity, by id and canonical name. */
+export interface RelationNode {
+    /** `entities.entity_id` — stable across renames of the display label. */
+    entity_id: number;
+    /** `entities.name`, the canonical name (an alias in the query resolves to this). */
+    name: string;
+}
+/**
+ * One hop of a relation path: the stored `subject —predicate→ object` of ONE edge, plus the fact it
+ * was extracted from. `fact_id` is the evidence — the row `mem_admin detail` opens — so a path is
+ * never a string answer without a source.
+ */
+export interface RelationPathEdge {
+    subject: string;
+    predicate: string;
+    object: string;
+    /**
+     * The ACTIVE fact this edge came from. Every edge of every path carries one: the relation stage
+     * never reuses a path whose evidence cannot be opened.
+     */
+    fact_id: number;
+    /** This edge's extractor confidence in `[0,1]`; the path's own `confidence` is the product of its edges'. */
+    confidence: number;
 }
+/** A complete relation path (RELATIONAL_RECALL §7), from the queried node to the node walked to. */
+export interface RelationPath {
+    start: RelationNode;
+    end: RelationNode;
+    /** Number of edges — 1 or 2 in this version ("最大 2 跳，不做任意递归"). */
+    hops: number;
+    /** The edges in walk order; `edges[0].subject` is `start.name` and the last `object` is `end.name`. */
+    edges: RelationPathEdge[];
+    /** Product of the edge confidences, rounded by the graph library. */
+    confidence: number;
+}
+/**
+ * The fact behind a relation answer.
+ *
+ * Deliberately NOT a {@link RecallHit}: a relation answer is not a ranked content match, so this
+ * shape has NO `score` (there is nothing to rank it against), and the handle a caller acts on is
+ * `fact_id` (`RecallHit` calls it `ref_id`). Keeping them apart is what stops a model from reading
+ * "this path's evidence" as "a relevance number".
+ */
+export interface RelationEvidence {
+    /** The fact id every path edge and `mem_admin detail` share. */
+    fact_id: number;
+    /** The fact's content, verbatim (bounded by the retrieval output budget, like a hit). */
+    text: string;
+    /** The memory layer, so a caller knows whether it is reading a journal or a note. */
+    memory_kind: MemoryKind;
+    title?: string;
+    created_at: string;
+    updated_at: string | null;
+    /** Set when the output budget shortened `text` (never when the evidence itself was dropped). */
+    truncated?: boolean;
+}
+/**
+ * `mem_recall.search` when the query named a relation the graph could answer
+ * (RELATIONAL_RECALL §6–7, Phase 4).
+ *
+ * It carries STRUCTURE (`paths`, each edge pointing at its fact) and the evidence rows — never a
+ * natural-language answer, and never a relevance score. An empty `paths` is not a relation result
+ * at all: the store falls back to {@link FuzzySearchResult} instead, so `mode:"relation"` always
+ * means "at least one path (and therefore at least one openable fact) was found".
+ *
+ * A PURE multi-entity question ("张伟和李娜") is not a relation question: it is answered at the
+ * fact level by {@link FactSearchResult} (`mode:"facts"`), over `fact_entities`, so journal entries
+ * and notes without any relation edge are covered. The graph library's `andPaths` is still available
+ * to adapters that want edge evidence, but `mem_recall.search` no longer routes a query to it.
+ */
+export interface RelationSearchResult {
+    mode: 'relation';
+    /** The paths, best first (confidence DESC, hops ASC, evidence recency DESC). */
+    paths: RelationPath[];
+    /** The distinct facts the paths' edges point at, in path order. */
+    evidence: RelationEvidence[];
+    /** Distinct candidate paths found before paging (`paths.length` may be smaller). */
+    total: number;
+    /** `true` when more paths existed than this result returns. */
+    truncated: boolean;
+}
+/**
+ * The citation handle of a fact row: `memory:fact:<id>`.
+ *
+ * ONE definition, because three surfaces spell this string: a {@link RecallHit}'s `source_ref`, a
+ * {@link FactEvidence}'s, and the model projection's fallback for a host that predates the field
+ * (an added field does not bump `WIRE_VERSION`, see `tools.ts#factsForModel`). The read surface
+ * DERIVES it — nothing is stored — so a handle that disagreed between two of them would be a
+ * citation the other surface cannot resolve (REVIEW-FACT-AND-R2 P2-1).
+ */
+export declare function factSourceRef(factId: number): string;
+/**
+ * The fact behind a fact-level AND answer (docs/GRAPH_RECALL_AND_SEMANTICS.md §7.9).
+ *
+ * Deliberately NOT a {@link RecallHit}: this is not a ranked content match, so the shape has NO
+ * `score` (there is nothing to rank it against), and the handle a caller acts on is `fact_id`
+ * (`RecallHit` calls it `ref_id`). `memory_kind` + `status` say which layer and which revision the
+ * fact is, and `event_date` is the journal axis (the stored `valid_from`).
+ */
+export interface FactEvidence {
+    /** The fact id `mem_admin detail` opens. */
+    fact_id: number;
+    /**
+     * The citation handle, spelled exactly as a {@link RecallHit}'s `source_ref`
+     * (`memory:fact:<id>`) so an answer can cite a fact page row the same way it cites a hit.
+     *
+     * It is DERIVED from `fact_id` (the read surface builds it; nothing is stored), which is why it
+     * says nothing about P-08 provenance — that is `mem_admin detail`'s `sources`. Carried anyway
+     * because a caller that only sees this page must be able to quote a source without a second call.
+     */
+    source_ref: string;
+    /** The fact's content, verbatim (bounded by the retrieval output budget, like a hit). */
+    content: string;
+    /** The memory layer, so a caller knows whether it is reading a journal or a note. */
+    memory_kind: MemoryKind;
+    /** `active` for every row this stage returns; carried so the field is explicit, not implied. */
+    status: FactStatus;
+    title?: string;
+    /** The fact's event time (`valid_from`), when it has one. */
+    event_date?: string;
+    created_at: string;
+    updated_at: string | null;
+    /** Set when the output budget shortened `content` (never when the fact itself was dropped). */
+    truncated?: boolean;
+}
+/**
+ * `mem_recall.search` when the query was a PURE multi-entity connection
+ * (docs/GRAPH_RECALL_AND_SEMANTICS.md §7.9): every `facts` row mentions EVERY entity the query
+ * named, and `total`/`offset`/`limit`/`truncated` page the FACTS, not paths or edges.
+ *
+ * An empty page is not a result at all — the store continues to the relation stage and then fuzzy —
+ * so `mode:"facts"` always means at least one fact was found, and the caller never has to tell an
+ * empty answer from a failed one.
+ */
+export interface FactSearchResult extends ExactPageEnvelope {
+    mode: 'facts';
+    /** The facts, newest row first, each mentioning every queried entity. */
+    facts: FactEvidence[];
+}
+/**
+ * The `mem_recall.search` payload — ONE type for the five modes, so a caller must look at `mode`
+ * before it reads pagination (an exact, time or facts page), the paths and evidence (a relation
+ * answer) or the retrieval diagnostics (a fuzzy answer).
+ */
+export type MemorySearchResult = ExactSearchResult | TimeSearchResult | FactSearchResult | RelationSearchResult | FuzzySearchResult;
+/** `mem_recall.titles` when one title is EXACTLY the query (case-sensitive; RECALL_INTERFACE §2.3). */
+export type ExactTitlesResult = ExactPageEnvelope & {
+    mode: 'exact';
+    candidates: TitleCandidate[];
+};
+/** `mem_recall.titles` when no title equals the query: the title-index shortlist, fixed at `topK = 5`. */
+export interface FuzzyTitlesResult {
+    mode: 'fuzzy';
+    candidates: TitleCandidate[];
+}
+/** The `mem_recall.titles` payload. */
+export type TitlesResult = ExactTitlesResult | FuzzyTitlesResult;
 /** P-01: one leg's contribution to a hit (see {@link RecallHit.scores}). */
 export interface RecallLegScore {
     /** The leg's own raw score, on its own scale. */
@@ -178,7 +495,11 @@ export interface RetrievalFloors {
     semantic: number;
     /** Distinct-query-term floor for the FTS leg (`retriever.min_fts_terms`; 1 when degraded). */
     fts: number;
-    /** Anchored query-coverage floor for the entity leg (`retriever.min_jaccard`, see `store/entity_leg.ts`). */
+    /**
+     * Configured LOWER BOUND of the entity leg's evidence bar (`retriever.min_jaccard`). The leg
+     * applies a per-candidate anchor-rarity bar on top of it, in the same anchored-overlap unit — see
+     * `store/entity_leg.ts` and DESIGN §20.19 续.
+     */
     jaccard: number;
 }
 /**
@@ -226,12 +547,21 @@ export interface RecallResult {
     };
     /**
      * The effective relevance floors for this query, when it ran through the hybrid orchestration.
-     * Absent on graph-only answers (`probe`/`chain`/`reason`/`related`), which never scored a leg.
+     * Absent on literal-only answers (an exact page) and non-hybrid payloads, which never scored a leg.
      * When {@link RecallResult.relaxed} is true these are the RELAXED values that produced the hits.
      */
     floors?: RetrievalFloors;
     /** Per-leg candidates removed by those floors (see {@link RetrievalFloorDrops}). */
     dropped_by_floor?: RetrievalFloorDrops;
+    /**
+     * Candidates the FUSED-score floor (`retriever.min_score`, default 0.5) removed after fusion.
+     *
+     * Absent when nothing was dropped (including when the floor is off). It is NOT part of
+     * `dropped_by_floor`: that structure attributes drops to a leg, and this threshold is applied after
+     * every leg has been fused. When {@link RecallResult.relaxed} is true this is the RELAXED pass's
+     * count, the same convention as `floors` / `dropped_by_floor`.
+     */
+    dropped_by_score?: number;
     /**
      * The strict floors emptied this query's result and ONE relaxed pass supplied these hits (`floors`
      * are that pass's values). Absent on an ordinary answer, on an explicit `floors: 'loose'` request
@@ -242,8 +572,8 @@ export interface RecallResult {
 }
 /**
  * Weights reported when the semantic leg is unavailable (FTS+entity rebalance).
- * Single source for both stores and the cross-retrieval router — previously the
- * same literal lived in three files and could silently desync.
+ * Single source for the store and every surface that reports them — previously the
+ * same literal lived in more than one file and could silently desync.
  */
 export declare const DEGRADED_WEIGHTS: RecallResult['weights'];
 /**
@@ -264,8 +594,9 @@ export interface ContradictionRecord {
     detected_at: string;
     content_a: string;
     content_b: string;
-    category_a: string | null;
-    category_b: string | null;
+    /** The two facts' memory layers (see {@link MEMORY_KINDS}); `null` on a legacy row. */
+    kind_a: string | null;
+    kind_b: string | null;
     resolved: number;
 }
 /**
@@ -541,271 +872,16 @@ export interface VectorsFixStoreReport {
     reindexed?: number;
 }
 /**
- * `mem_admin vectors_fix`: what a repair did, or — with `dry_run` — what it WOULD do, per store.
+ * `mem_admin vectors_fix`: what a repair did, or — with `dry_run` — what it WOULD do.
  *
- * The report is per-store because one switch and one call now cover BOTH libraries (a model swap
- * leaves memory and knowledge in the same state, and the repair used to exist for memory only).
- * `store` on the request narrows the call to one library; the top-level `semantic_available` is the
- * AND over the stores actually repaired.
+ * The wrapper is kept separate from {@link VectorsFixStoreReport} because the repair reports a
+ * store-level result and a call-level one: `semantic_available` is "the model was available for
+ * the whole call", while the store report carries the counts.
  */
 export interface VectorsFixReport {
     stores: {
         memory?: VectorsFixStoreReport;
-        knowledge?: VectorsFixStoreReport;
     };
     semantic_available: boolean;
     dry_run: boolean;
 }
-/** `kb_manage ingest`: what one document produced. */
-export interface IngestResult {
-    doc_id: number;
-    chunks: number;
-    /**
-     * How many chunks did NOT get a semantic vector. Absent when every chunk did, so a healthy ingest
-     * stays as quiet as it was.
-     *
-     * `chunks` counts what was CHUNKED, not what became semantically searchable: an encode failure (no
-     * model, bad input) or a write failure (`SQLITE_BUSY` under multi-process contention) skips that
-     * chunk while the text/entity/FTS indexes stay complete. Reporting the shortfall here is what stops
-     * "入库成功 N 段" from implying "N 段都能被语义检索到" — before this, the only way to find out was to
-     * run `kb_reindex` and compare `vectors_stale` against `vectors_encoded`. A missing embedding model
-     * reports every chunk, which is the honest reading of "indexed, but not semantically".
-     */
-    vectors_failed?: number;
-    /**
-     * How the source bytes became text: `utf-8`, `utf-8-bom`, `utf-16le`, `utf-16be` or `gb18030`
-     * (absent for pasted text, for a document pulled back from its managed file, and for a PDF —
-     * whose text comes from an extracted layer rather than from a byte encoding). Reported because
-     * decoding a legacy-encoded file is a GUESS the caller should be able to see.
-     */
-    encoding?: string;
-    /**
-     * Which converter turned the source into Markdown — `docx`, `xlsx`, `html` or `csv` (absent for
-     * text, PDF, and a body re-read from its managed file). The body is derived rather than read in
-     * that case, so the caller is told what derived it.
-     */
-    converter?: string;
-    /** What that conversion could not carry over (dropped media, a truncated sheet, ragged rows). */
-    warnings?: string[];
-    /** The managed file this ingest wrote (`knowledge.docs.dir/<domain>/<source>/<title>.md`). */
-    file?: string;
-    /** Why the managed file could not be written; the document itself is still searchable. */
-    file_error?: string;
-}
-/**
- * One existing document an ingest would land on — the machine-readable half of a collision.
- *
- * `path` is the managed `.md` copy (`knowledge.docs.dir/<domain>/<source>/<title>.md`), which is
- * what the caller edits to change that document; `doc_id`/`title` are what it takes to name the
- * collision. Reported by BOTH the add-only refusal (as text, for the agent) and the replace
- * confirmation (as a list, for the UI's dialog and the CLI).
- */
-export interface KbIngestConflict {
-    doc_id: number;
-    title: string;
-    path: string;
-}
-/**
- * What `kb_manage` answers when a write would REPLACE an existing document and the caller did not
- * confirm it. `conflict: true` is the flag the UI's 入库 form and the CLI dispatch on; nothing was
- * written when this comes back, so "取消" is a no-op rather than a rollback.
- *
- * `would_overwrite`/`would_add` are the summary the confirmation dialog shows ("将覆盖 N 篇 /
- * 新增 M 篇") — computed at plan time, when the targets are known, rather than re-derived by the
- * caller from `conflicts`.
- */
-export interface KbConflictReport {
-    conflict: true;
-    /** Chinese, actionable: names the colliding documents and says nothing was written. */
-    error: string;
-    conflicts: KbIngestConflict[];
-    would_overwrite: number;
-    would_add: number;
-}
-/**
- * `kb_manage import`: what landed, what failed (with the reason), and what was skipped.
- *
- * `skipped` is the DIRECTORY walk's rejections (files whose name is not an ingestable format) — a
- * silent list before this, which made "3 of 200 files imported" indistinguishable from "3 files".
- * Only the first `SKIPPED_REPORTED` (a `core` constant) paths are listed; `skipped_total` is the real count.
- */
-export interface ImportResult {
-    imported: IngestResult[];
-    failed: {
-        path: string;
-        error: string;
-    }[];
-    skipped: string[];
-    skipped_total: number;
-}
-/**
- * One document's managed file, as the file system sees it right now.
- *
- * `stale` means the file's body no longer matches what the KB indexed (someone edited it and
- * the change has not been ingested); `missing` means there is no file for this document (never
- * written, deleted by hand, or replaced by another document's file).
- */
-export interface KbDocFile {
-    doc_id: number;
-    title: string;
-    path: string;
-    stale: boolean;
-    missing: boolean;
-}
-/**
- * `kb_manage sync`: the managed files vs what the KB indexed.
- *
- * `stale` is the plan and `reingested` what happened (equal unless `dry_run`); `orphans` are
- * managed files with no document behind them — left by a hand-deleted row, and safe to delete.
- */
-export interface KbSyncReport {
-    checked: number;
-    stale: KbDocFile[];
-    missing: KbDocFile[];
-    orphans: string[];
-    /**
-     * Files that sit exactly where a document's path says its own copy belongs, yet do not claim that
-     * document — a whole-file overwrite that destroyed the frontmatter.
-     *
-     * These ARE recovered automatically, but only behind guards: no `doc_id` at all, a non-empty
-     * body, a stamp that holds still (see `ADOPT_SETTLE_MS`) and a path exactly one document maps
-     * to. A candidate that fails any of them stays here, unclaimed, and `sync {adopt: true}` is the
-     * explicit per-document way to take it back immediately.
-     */
-    unclaimed: KbUnclaimedFile[];
-    reingested: number;
-    /** How many documents this call adopted (`sync {adopt: true}`); 0 otherwise. */
-    adopted: number;
-    dry_run: boolean;
-}
-/** One adoptable file: its path names this document, but the file does not claim it. */
-export interface KbUnclaimedFile {
-    doc_id: number;
-    title: string;
-    path: string;
-}
-/**
- * `kb_manage reindex`: what it did, and what it deliberately did NOT redo (DESIGN §20).
- *
- * `vectors_stale` is the plan and `vectors_encoded` what happened; they differ when the embedder
- * is unavailable, which is the case a caller needs to see instead of "nothing to do".
- */
-export interface ReindexReport {
-    chunks: number;
-    entities_rebuilt: number;
-    vectors_stale: number;
-    vectors_encoded: number;
-    semantic_available: boolean;
-    dry_run: boolean;
-}
-/** `kb_manage list`: the stored document columns (everything but `meta`/`status`). */
-export interface DocumentSummary {
-    doc_id: number;
-    domain: string;
-    source: string;
-    title: string;
-    source_uri: string | null;
-    created_at: string;
-    updated_at: string;
-}
-/** The full stored document row (`kb detail` minus its chunks). */
-export interface DocumentRecord extends DocumentSummary {
-    meta: string;
-    status: string;
-}
-/** One stored chunk as `kb detail` returns it. */
-export interface DocumentChunk {
-    chunk_id: number;
-    idx: number;
-    text: string;
-    headings_path: string;
-    source_ref: string;
-}
-/** `kb_manage detail`: the document row plus its chunks, in document order. */
-export interface DocumentDetail extends DocumentRecord {
-    chunks: DocumentChunk[];
-}
-/** What one `kb_manage` source string turned out to be. */
-export type SourceKind = 'url' | 'file' | 'directory' | 'text' | 'missing';
-/**
- * The answer the UI needs to label the input and pick the right `kb_manage` action.
- *
- * It lives in the CONTRACT rather than next to the engine that computes it, because the browser half
- * cannot import the engine (it must not pull node into the client bundle) and used to hand-mirror this
- * shape — the same "mirror drifts, then a render body dereferences a field the host stopped sending"
- * failure that has already cost this family once.
- */
-export interface SourceClassification {
-    readonly kind: SourceKind;
-    /** Resolved, boundary-checked absolute paths (when `kind` is `file`/`directory`). */
-    readonly paths: readonly string[];
-    /** Inputs that look like paths but do not resolve, or resolve outside the allowed roots. */
-    readonly missing: readonly string[];
-    /** Why the missing ones are missing (the boundary's own message; they differ per input). */
-    readonly reasons: readonly string[];
-    /** How many files a directory holds that ingestion would actually take. */
-    readonly files: number;
-}
-/** One row of a directory listing (the 选择 picker's `browseDir`). */
-export interface BrowseEntry {
-    readonly name: string;
-    readonly path: string;
-    /** `dir` navigates; `ingestable` can be picked; `other` exists but ingestion would refuse it. */
-    readonly kind: 'dir' | 'ingestable' | 'other';
-}
-/**
- * One directory as the browser picker sees it.
- *
- * Pinned to the engine's `browseDirectory` return BY the host Remote declaration, which annotates its
- * payload with this interface: the two cannot drift without a type error. That check is the reason this
- * shape is spelled here rather than mirrored in the browser half.
- */
-export interface BrowseListing {
-    readonly path: string;
-    /** The parent directory, or `null` when this is an allowed root (or the filesystem root). */
-    readonly parent: string | null;
-    /** The configured roots — what the picker may walk when `unrestricted` is false. */
-    readonly roots: readonly string[];
-    /**
-     * `knowledge.ingest.allow_outside_workspace`: the whole filesystem is fair game, so `roots` is
-     * informational only and the UI must say "不限制" rather than show a boundary it does not honour.
-     */
-    readonly unrestricted: boolean;
-    readonly entries: readonly BrowseEntry[];
-}
-/**
- * The 知识页 domain picker's option list: the configured `knowledge.domains` allowlist ∪ the
- * domains the library already holds, plus whether the allowlist is active.
- *
- * `restricted` mirrors "the allowlist is non-empty": then the control is a closed `<select>` and a
- * new domain is a config change, not a second spelling of an existing one; an explicitly empty
- * allowlist means no restriction, so the control stays a free input. The union half is not a
- * compatibility layer — without it, narrowing the allowlist would make every existing document
- * un-re-ingestable.
- *
- * It lives in the CONTRACT rather than being mirrored on both halves for the reason every UI payload
- * here does: the host half declared it as an anonymous shape and the browser half hand-copied it,
- * which is exactly how a field goes missing. `KnowledgeStore.domainCatalog()` / `addDomain()` (the
- * real producers) and the picker (the real consumer) now name this one type.
- */
-export interface DomainCatalog {
-    readonly domains: readonly string[];
-    readonly restricted: boolean;
-}
-/** Which of the two things a document row can open (`openDoc`). */
-export type OpenTarget = 'file' | 'dir';
-/**
- * What `openDoc` launched, for the UI's status line.
- *
- * In the contract, not beside `openDocumentPath` (the host-side producer), for the same reason as
- * {@link DomainCatalog}: the browser half cannot import that module — it pulls `node:child_process` —
- * and used to hand-copy `{ path, opener }` (dropping `target`). The host Remote declaration annotates
- * its payload with this interface, so producer and wire cannot drift without a type error.
- */
-export interface OpenOutcome {
-    /** The managed path actually handed to the opener (the file, or the directory holding it). */
-    readonly path: string;
-    readonly target: OpenTarget;
-    /** The command that was actually used (`code`, `explorer.exe`, …). */
-    readonly opener: string;
-}