@avantf/dsh-mem 0.6.4 → 0.8.0

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

@@ -1,6 +1,42 @@
 import { z } from 'zod';
+import { type StatusFilter } from './types.js';
+/**
+ * One structured relation a WRITE may declare (STRUCTURED_RELATIONS §2).
+ *
+ * It is the caller STATING a relation, not the extractor guessing one, which is why
+ * `kind: "note"` is the only layer that accepts it: a journal entry is an episode, and a relation
+ * that is worth remembering is a fact about the world (promote it: write a note, `source_ref` it
+ * back to the journal). Every slot is a NAME — the engine runs it through the same entity/predicate
+ * normalization and the same name-shape gate the extractor's edges pass.
+ */
+export declare const RelationInputSchema: z.ZodObject<{
+    subject: z.ZodString;
+    predicate: z.ZodString;
+    object: z.ZodString;
+}, z.core.$strict>;
+/** One structured relation, as a write carries it. */
+export type RelationInput = z.infer<typeof RelationInputSchema>;
+/**
+ * How many relations ONE write may declare.
+ *
+ * A single fact states a handful of relations; a caller passing dozens has stopped describing a
+ * fact and started importing a graph. The cap keeps one call's work bounded (and the tool argument
+ * readable) without pretending to be a per-fact model of the corpus.
+ */
+export declare const MAX_RELATIONS_PER_WRITE = 20;
 export declare const CONTRADICTION_RESOLUTIONS: readonly ["true_positive", "false_positive"];
-export declare const QUERY_KINDS: readonly ["all", "fact", "doc_chunk"];
+/** The `time` object of `mem_recall`'s two time-aware actions. */
+export declare const TimeFilterSchema: z.ZodObject<{
+    field: z.ZodEnum<{
+        created: "created";
+        updated: "updated";
+        event: "event";
+    }>;
+    on: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+    timezone: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 /**
  * The longest retrieval query the contract accepts, in characters.
  *
@@ -35,7 +71,7 @@ export declare const MAX_REPORTED_CONFLICTS = 20;
  */
 export declare const RETENTION_VOCABULARY: readonly ["衰减", "消退", "遗忘", "强化", "活跃使用日", "信任度", "永久记忆", "长期有效的信息"];
 /**
- * Admin actions that return a FACT VIEW. Their payload goes through
+ * The admin actions that return a FACT VIEW. Their payload goes through
  * {@link modelFacingToolResult}, which drops the retention diagnostics; the other admin
  * actions (`trust_diagnose`, `vectors_diagnose`, …) are diagnostics the caller asked for and
  * pass through untouched.
@@ -48,24 +84,50 @@ export declare const FACT_VIEW_ADMIN_ACTIONS: readonly ["list", "detail"];
  * explicitly with `mem_admin`'s diagnostic actions.
  */
 export declare function modelFacingToolResult(toolKey: string, action: unknown, value: unknown): unknown;
+/**
+ * The statuses an export may narrow to. Declared here (next to the tool schema that exposes it) so
+ * the core export path, the CLI flag validation and the admin action read ONE set: a value added
+ * here moves the contract, the CLI and the engine together.
+ */
+export declare const EXPORT_STATUSES: readonly ["active", "archived", "all"];
+export type ExportStatus = StatusFilter;
 export declare const REMEMBER_ACTIONS: readonly ["add", "update", "remove", "helpful", "unhelpful"];
 export declare const RememberUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     action: z.ZodLiteral<"add">;
     content: z.ZodString;
-    category: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        journal: "journal";
+        note: "note";
+    }>>;
+    title: z.ZodOptional<z.ZodString>;
     ttl_days: z.ZodOptional<z.ZodNumber>;
     source_ref: z.ZodOptional<z.ZodString>;
     event_date: z.ZodOptional<z.ZodString>;
     valid_until: z.ZodOptional<z.ZodString>;
+    relations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        subject: z.ZodString;
+        predicate: z.ZodString;
+        object: z.ZodString;
+    }, z.core.$strict>>>;
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"update">;
     fact_id: z.ZodNumber;
     content: z.ZodString;
-    category: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        journal: "journal";
+        note: "note";
+    }>>;
+    title: z.ZodOptional<z.ZodString>;
+    retitle: z.ZodOptional<z.ZodLiteral<true>>;
     ttl_days: z.ZodOptional<z.ZodNumber>;
     source_ref: z.ZodOptional<z.ZodString>;
     event_date: z.ZodOptional<z.ZodString>;
     valid_until: z.ZodOptional<z.ZodString>;
+    relations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        subject: z.ZodString;
+        predicate: z.ZodString;
+        object: z.ZodString;
+    }, z.core.$strict>>>;
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"remove">;
     fact_id: z.ZodNumber;
@@ -77,13 +139,36 @@ export declare const RememberUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     action: z.ZodLiteral<"unhelpful">;
     fact_id: z.ZodNumber;
 }, z.core.$strip>], "action">;
+/**
+ * The runtime/CLI-visible write request. The base zod union keeps `kind` optional so the CLI's
+ * `add` without `--kind` (new row -> note) and `edit` without it (inherit the replaced row) keep
+ * working; the MODEL-facing `ModelRememberUnion` below re-declares it as required (N7).
+ */
 export type RememberRequest = z.infer<typeof RememberUnion>;
-export declare const RECALL_ACTIONS: readonly ["search", "ask", "chain", "probe", "reason", "related", "contradict"];
+/**
+ * The writes the model may make. `helpful` / `unhelpful` are operator feedback: the model cannot
+ * observe the retention clocks they move, and a model that could would be able to "refresh" a fact by
+ * voting on it — the exact behaviour the retention policy exists to prevent.
+ */
+export declare const MODEL_REMEMBER_ACTIONS: readonly ["add", "update", "remove"];
+export declare const ModelRememberUnion: z.ZodDiscriminatedUnion<readonly z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>[], string>;
+/**
+ * The public recall surface: TWO actions (docs/RECALL_INTERFACE.md).
+ *
+ * The engine decides whether a query is answered by the literal (exact) pass or by the fuzzy
+ * retrieval; the caller never chooses, never passes a relevance threshold, and never sees the
+ * pagination knobs of the fuzzy pass. `search` is content, `titles` is title — nothing else.
+ */
+export declare const RECALL_ACTIONS: readonly ["search", "titles"];
 export declare const RecallUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     action: z.ZodLiteral<"search">;
-    query: z.ZodString;
-    category: z.ZodOptional<z.ZodString>;
+    query: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        journal: "journal";
+        note: "note";
+    }>>;
     source: z.ZodOptional<z.ZodString>;
+    offset: z.ZodOptional<z.ZodNumber>;
     limit: z.ZodOptional<z.ZodNumber>;
     max_tokens: z.ZodOptional<z.ZodNumber>;
     floors: z.ZodOptional<z.ZodEnum<{
@@ -91,51 +176,76 @@ export declare const RecallUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
         loose: "loose";
     }>>;
     include_scores: z.ZodOptional<z.ZodBoolean>;
+    time: z.ZodOptional<z.ZodObject<{
+        field: z.ZodEnum<{
+            created: "created";
+            updated: "updated";
+            event: "event";
+        }>;
+        on: z.ZodOptional<z.ZodString>;
+        from: z.ZodOptional<z.ZodString>;
+        to: z.ZodOptional<z.ZodString>;
+        timezone: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strip>, z.ZodObject<{
-    action: z.ZodLiteral<"ask">;
-    subj: z.ZodOptional<z.ZodString>;
-    pred: z.ZodOptional<z.ZodString>;
-    obj: z.ZodOptional<z.ZodString>;
-    query: z.ZodOptional<z.ZodString>;
-    limit: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>, z.ZodObject<{
-    action: z.ZodLiteral<"chain">;
-    subj: z.ZodString;
-    pred: z.ZodOptional<z.ZodString>;
-    second_pred: z.ZodOptional<z.ZodString>;
-    limit: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>, z.ZodObject<{
-    action: z.ZodLiteral<"probe">;
-    entity: z.ZodString;
-    category: z.ZodOptional<z.ZodString>;
-    limit: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>, z.ZodObject<{
-    action: z.ZodLiteral<"reason">;
-    entities: z.ZodArray<z.ZodString>;
-    category: z.ZodOptional<z.ZodString>;
-    limit: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>, z.ZodObject<{
-    action: z.ZodLiteral<"related">;
-    entity: z.ZodString;
-    category: z.ZodOptional<z.ZodString>;
-    limit: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>, z.ZodObject<{
-    action: z.ZodLiteral<"contradict">;
-    category: z.ZodOptional<z.ZodString>;
+    action: z.ZodLiteral<"titles">;
+    query: z.ZodString;
+    kind: z.ZodOptional<z.ZodEnum<{
+        journal: "journal";
+        note: "note";
+    }>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        archived: "archived";
+        all: "all";
+    }>>;
+    time: z.ZodOptional<z.ZodObject<{
+        field: z.ZodEnum<{
+            created: "created";
+            updated: "updated";
+            event: "event";
+        }>;
+        on: z.ZodOptional<z.ZodString>;
+        from: z.ZodOptional<z.ZodString>;
+        to: z.ZodOptional<z.ZodString>;
+        timezone: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    offset: z.ZodOptional<z.ZodNumber>;
     limit: z.ZodOptional<z.ZodNumber>;
+    include_excerpt: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>], "action">;
 export type RecallRequest = z.infer<typeof RecallUnion>;
-export declare const ADMIN_ACTIONS: readonly ["stats", "list", "detail", "archive", "restore", "pin", "unpin", "trust_diagnose", "vectors_diagnose", "vectors_fix", "contradict_check", "contradict_resolve", "maintenance"];
+/**
+ * The retrieval actions the model may call: content and title, nothing else. Exact-vs-fuzzy,
+ * thresholds, topK and paging are the ENGINE's rules (docs/RECALL_INTERFACE.md §1).
+ */
+export declare const MODEL_RECALL_ACTIONS: readonly ["search", "titles"];
+export declare const ModelRecallUnion: z.ZodDiscriminatedUnion<readonly z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>[], string>;
+export declare const ADMIN_ACTIONS: readonly ["stats", "list", "detail", "archive", "restore", "pin", "unpin", "trust_diagnose", "vectors_diagnose", "vectors_fix", "contradict_check", "contradict_resolve", "contradictions", "maintenance", "export", "import", "merge", "restore_snapshot"];
 export declare const AdminUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     action: z.ZodLiteral<"stats">;
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"list">;
-    category: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        journal: "journal";
+        note: "note";
+    }>>;
     status: z.ZodOptional<z.ZodEnum<{
         active: "active";
         archived: "archived";
     }>>;
     source: z.ZodOptional<z.ZodString>;
+    time: z.ZodOptional<z.ZodObject<{
+        field: z.ZodEnum<{
+            created: "created";
+            updated: "updated";
+            event: "event";
+        }>;
+        on: z.ZodOptional<z.ZodString>;
+        from: z.ZodOptional<z.ZodString>;
+        to: z.ZodOptional<z.ZodString>;
+        timezone: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     limit: z.ZodOptional<z.ZodNumber>;
     offset: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
@@ -161,12 +271,15 @@ export declare const AdminUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"vectors_fix">;
     dry_run: z.ZodOptional<z.ZodBoolean>;
-    store: z.ZodOptional<z.ZodEnum<{
-        memory: "memory";
-        knowledge: "knowledge";
-    }>>;
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"contradict_check">;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"contradictions">;
+    kind: z.ZodOptional<z.ZodEnum<{
+        journal: "journal";
+        note: "note";
+    }>>;
+    limit: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"contradict_resolve">;
     contradiction_id: z.ZodNumber;
@@ -177,65 +290,41 @@ export declare const AdminUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     loser_fact_id: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"maintenance">;
-}, z.core.$strip>], "action">;
-export type AdminRequest = z.infer<typeof AdminUnion>;
-/** The `source` a write gets when it omits one; a document's identity is `(domain, source, title)`. */
-export declare const DEFAULT_KB_SOURCE = "default";
-export declare const KbUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    action: z.ZodLiteral<"ingest">;
-    text: z.ZodOptional<z.ZodString>;
-    source_uri: z.ZodOptional<z.ZodString>;
-    domain: z.ZodString;
-    source: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    title: z.ZodOptional<z.ZodString>;
-    overwrite: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
-    action: z.ZodLiteral<"import">;
-    paths: z.ZodArray<z.ZodString>;
-    domain: z.ZodString;
-    source: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    overwrite: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip>, z.ZodObject<{
-    action: z.ZodLiteral<"list">;
-    domain: z.ZodOptional<z.ZodString>;
-    source: z.ZodOptional<z.ZodString>;
-    limit: z.ZodOptional<z.ZodNumber>;
-    offset: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>, z.ZodObject<{
-    action: z.ZodLiteral<"detail">;
-    doc_id: z.ZodNumber;
+    action: z.ZodLiteral<"export">;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        archived: "archived";
+        all: "all";
+    }>>;
+    file: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
-    action: z.ZodLiteral<"remove">;
-    doc_id: z.ZodNumber;
+    action: z.ZodLiteral<"import">;
+    file: z.ZodString;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
-    action: z.ZodLiteral<"reindex">;
-    domain: z.ZodOptional<z.ZodString>;
+    action: z.ZodLiteral<"merge">;
+    file: z.ZodString;
     dry_run: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
-    action: z.ZodLiteral<"sync">;
-    doc_id: z.ZodOptional<z.ZodNumber>;
-    adopt: z.ZodOptional<z.ZodBoolean>;
+    action: z.ZodLiteral<"restore_snapshot">;
+    file: z.ZodString;
+    confirm: z.ZodLiteral<true>;
     dry_run: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>], "action">;
-export type KbRequest = z.infer<typeof KbUnion>;
-export declare const QueryUnion: z.ZodObject<{
-    query: z.ZodString;
-    kind: z.ZodOptional<z.ZodEnum<{
-        fact: "fact";
-        doc_chunk: "doc_chunk";
-        all: "all";
-    }>>;
-    max_tokens: z.ZodOptional<z.ZodNumber>;
-    domain: z.ZodOptional<z.ZodString>;
-    source: z.ZodOptional<z.ZodString>;
-    limit: z.ZodDefault<z.ZodNumber>;
-    floors: z.ZodOptional<z.ZodEnum<{
-        strict: "strict";
-        loose: "loose";
-    }>>;
-    include_scores: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip>;
-export type QueryRequest = z.infer<typeof QueryUnion>;
+export type AdminRequest = z.infer<typeof AdminUnion>;
+/**
+ * The admin actions the model may call: a fact page plus the backup/restore family.
+ *
+ * Everything else is OPERATOR machinery: diagnostics and repairs (the model cannot see trust values
+ * and must not rerun the embedding strategy), curation (pin/archive/contradiction verdicts), and
+ * duplicates of what is already model-facing (`detail` is a single-fact view of the same page;
+ * `contradictions` is the operator's list of open pairs, plus its verdict action; `merge` is what
+ * `import` now does automatically for a SQLite file). The full union stays for the runtime, the
+ * Remote gateway (the settings page drives every action) and the CLI.
+ */
+export declare const MODEL_ADMIN_ACTIONS: readonly ["list", "contradictions", "export", "import", "restore_snapshot"];
+export declare const ModelAdminUnion: z.ZodDiscriminatedUnion<readonly z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>[], string>;
 /** Transport-agnostic tool spec: name / key / description / zod input. */
 export interface ToolSpec {
     key: string;
@@ -246,28 +335,6 @@ export interface ToolSpec {
 export declare const REMEMBER_TOOL: ToolSpec;
 export declare const RECALL_TOOL: ToolSpec;
 export declare const ADMIN_TOOL: ToolSpec;
-export declare const KB_TOOL: ToolSpec;
-export declare const QUERY_TOOL: ToolSpec;
-/** One new document, or a batch import — never an update (see the tool description). */
-export declare const KB_ADD_TOOL: ToolSpec;
-/**
- * The parsed `kb_add` input, no `overwrite`: the add-only MODE is a property of the runtime face
- * (`rt.kbAdd`), not a field the model can set. Spelled out (rather than `z.infer` of
- * `KB_ADD_TOOL.input`, which is widened to `z.ZodType` by `ToolSpec`) so the runtime method and the
- * plugin handler agree on the request. `source` is present because the contract defaults it.
- */
-export interface KbAddRequest {
-    domain: string;
-    source: string;
-    title?: string;
-    text?: string;
-    source_uri?: string;
-    paths?: string[];
-}
-/** The corpus listing, with the managed path — the entry point for editing a document. */
-export declare const KB_LIST_TOOL: ToolSpec;
-export declare const KB_REMOVE_TOOL: ToolSpec;
-export declare const KB_REINDEX_TOOL: ToolSpec;
 export declare const TOOL_SPECS: ToolSpec[];
 /**
  * Compose the top-level (merged) description for a union field.