recallnest 2.3.0 → 2.6.0

package/src/skill-promotion.ts

@@ -12,6 +12,7 @@
 import type { MemoryEntry, MemoryStore } from "./store.js";
 import { cosineSimilarity } from "./multi-vector.js";
 import { isActiveMemory } from "./memory-evolution.js";
+import { verifyDraft, type VerifyResult } from "./skill-verifier.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -25,12 +26,20 @@ export interface PromotionCandidate {
   /** For pattern_to_skill: extracted implementation steps */
   suggestedImplementation?: string;
   confidence: number; // 0-1
+  /** A2: zero-LLM verifier verdict (pattern_to_skill only). 失败候选保留披露、排后、不静默丢。 */
+  verification?: VerifyResult;
+  /** Read-signal evidence aggregated from source entries（Artel 读驱动升华：被真实读过的候选提权）。 */
+  readEvidence?: { totalAccess: number; distinctReaders: number };
 }
 
 export interface PromotionScanResult {
   candidates: PromotionCandidate[];
   scannedCases: number;
   scannedPatterns: number;
+  /** No-silent-caps 披露:被桶上限截断、未参与聚类的 case 数。 */
+  truncatedCases: number;
+  /** 向量回填失败(库中无向量)而被跳过的条目数。 */
+  vectorlessSkipped: number;
 }
 
 export interface PromotionConfig {
@@ -40,24 +49,138 @@ export interface PromotionConfig {
   caseSimilarityThreshold: number;
   /** Max candidates to return (default: 5) */
   maxCandidates: number;
+  /** 全量扫描上限(防 OOM,default: 20000)。cases/patterns 各自独立适用。 */
+  maxScanEntries: number;
+  /** 单桶聚类上限(default: 2000)。桶内按 recency 保留,截断量计入 truncatedCases。 */
+  maxBucketSize: number;
+  /** listPage 翻页大小 (default: 1000)。 */
+  pageSize: number;
+  /** pattern_to_skill 通道最多探测的 structured patterns 数(每个一次 vectorSearch,
+   *  default: 1000,按 recency 优先)。 */
+  maxPatternProbes: number;
 }
 
 const DEFAULT_CONFIG: PromotionConfig = {
   minCaseOccurrences: 3,
   caseSimilarityThreshold: 0.75,
   maxCandidates: 5,
+  maxScanEntries: 20_000,
+  maxBucketSize: 2_000,
+  pageSize: 1_000,
+  maxPatternProbes: 1_000,
 };
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-type PromotionStore = Pick<MemoryStore, "list" | "vectorSearch">;
+type PromotionStore = Pick<MemoryStore, "listPage" | "getVectors" | "vectorSearch">;
 
 function isActive(entry: MemoryEntry): boolean {
   return isActiveMemory(entry.metadata);
 }
 
+/**
+ * 翻页拉取一个 category 的全部条目(轻列,不含向量)。
+ * listPage 在 DB 层下推 where/limit/offset,不会像 list() 那样每页全表拉取。
+ */
+async function listAllByCategory(
+  store: PromotionStore,
+  scope: string,
+  category: string,
+  maxEntries: number,
+  pageSize: number,
+  truncateTextTo?: number,
+): Promise<MemoryEntry[]> {
+  const out: MemoryEntry[] = [];
+  for (let offset = 0; out.length < maxEntries; offset += pageSize) {
+    const requested = Math.min(pageSize, maxEntries - out.length);
+    const page = await store.listPage({
+      scopeFilter: [scope],
+      category,
+      limit: requested,
+      offset,
+    });
+    for (const e of page) {
+      // 扫描只用 text 的头部(extractName 首行 / summarize 前 80 字 / 聚类靠向量),
+      // bridge 对话 case 全文很长,2 万条常驻能到 GB 级——截断防内存膨胀。
+      out.push(
+        truncateTextTo !== undefined && e.text.length > truncateTextTo
+          ? { ...e, text: e.text.slice(0, truncateTextTo) }
+          : e,
+      );
+    }
+    if (page.length < requested) break;
+  }
+  return out;
+}
+
+/** 从 metadata JSON 读 topicTag(缺失/解析失败 → undefined)。 */
+function readTopicTag(entry: MemoryEntry): string | undefined {
+  try {
+    const parsed: unknown = JSON.parse(entry.metadata || "{}");
+    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+      const tag = (parsed as Record<string, unknown>).topicTag;
+      return typeof tag === "string" && tag.length > 0 ? tag : undefined;
+    }
+  } catch { /* fallthrough */ }
+  return undefined;
+}
+
+/**
+ * A2: 抽 entry 的工具名供 verifier tool-coverage 用。
+ * metadata.{caseMemory|workflowPattern}.tools 优先；fallback 解析正文 `Tools: a, b, c` 行。
+ */
+function extractToolsFromEntry(entry: MemoryEntry): string[] {
+  try {
+    const parsed: unknown = JSON.parse(entry.metadata || "{}");
+    if (parsed !== null && typeof parsed === "object") {
+      const obj = parsed as Record<string, unknown>;
+      for (const key of ["caseMemory", "workflowPattern"]) {
+        const sub = obj[key];
+        if (sub !== null && typeof sub === "object") {
+          const tools = (sub as Record<string, unknown>).tools;
+          if (Array.isArray(tools)) {
+            return tools.filter((t): t is string => typeof t === "string" && t.length > 0);
+          }
+        }
+      }
+    }
+  } catch { /* fallthrough to text parse */ }
+  const m = entry.text.match(/(?:^|\n)Tools:\s*(.+)/);
+  if (m) return m[1].split(",").map(t => t.trim()).filter(Boolean);
+  return [];
+}
+
+/**
+ * 按 topicTag 分桶(无 tag → "untagged" 桶),桶内按 recency 保留 maxBucketSize 条。
+ * 分桶把 greedyCluster 的 O(n²) 最坏复杂度限制在桶内,同时避免全库向量常驻。
+ */
+function bucketByTopic(
+  entries: MemoryEntry[],
+  maxBucketSize: number,
+): { buckets: Map<string, MemoryEntry[]>; truncated: number } {
+  const buckets = new Map<string, MemoryEntry[]>();
+  for (const e of entries) {
+    const key = readTopicTag(e) ?? "untagged";
+    let bucket = buckets.get(key);
+    if (!bucket) {
+      bucket = [];
+      buckets.set(key, bucket);
+    }
+    bucket.push(e);
+  }
+  let truncated = 0;
+  for (const [key, bucket] of buckets) {
+    if (bucket.length > maxBucketSize) {
+      bucket.sort((a, b) => (b.timestamp || 0) - (a.timestamp || 0));
+      truncated += bucket.length - maxBucketSize;
+      buckets.set(key, bucket.slice(0, maxBucketSize));
+    }
+  }
+  return { buckets, truncated };
+}
+
 /** Extract a short name from the first case's text (first line or first ~60 chars). */
 function extractName(text: string): string {
   const firstLine = text.split("\n")[0].trim();
@@ -95,12 +218,12 @@ function extractSteps(text: string): string {
 // Greedy Clustering (same approach as consolidation-engine's C-2)
 // ---------------------------------------------------------------------------
 
-interface Cluster {
+export interface Cluster {
   seed: MemoryEntry;
   members: MemoryEntry[];
 }
 
-function greedyCluster(
+export function greedyCluster(
   entries: MemoryEntry[],
   threshold: number,
 ): Cluster[] {
@@ -145,6 +268,47 @@ function greedyCluster(
   return clusters;
 }
 
+// ---------------------------------------------------------------------------
+// Read evidence (Artel-style read-driven promotion)
+// ---------------------------------------------------------------------------
+
+/** Max confidence boost from read evidence. Saturates at 4 distinct readers. */
+const READ_BOOST_MAX = 0.15;
+
+/**
+ * Aggregate read signals (accessCount / readerIds / distinctReaderCount, written
+ * by AccessTracker on retrieval) across a candidate's source entries.
+ * distinctReaders = max(union of readerIds, per-entry saturated count) — the
+ * union undercounts once READER_ID_CAP saturates, the per-entry count covers that.
+ */
+export function aggregateReadEvidence(
+  entries: Array<{ metadata?: string }>,
+): { totalAccess: number; distinctReaders: number } {
+  let totalAccess = 0;
+  const readers = new Set<string>();
+  let saturatedMax = 0;
+  for (const e of entries) {
+    try {
+      const meta = JSON.parse(e.metadata || "{}") as Record<string, unknown>;
+      if (typeof meta.accessCount === "number") totalAccess += meta.accessCount;
+      if (Array.isArray(meta.readerIds)) {
+        for (const r of meta.readerIds) if (typeof r === "string") readers.add(r);
+      }
+      if (typeof meta.distinctReaderCount === "number") {
+        saturatedMax = Math.max(saturatedMax, meta.distinctReaderCount);
+      }
+    } catch { /* broken metadata → contributes nothing */ }
+  }
+  return { totalAccess, distinctReaders: Math.max(readers.size, saturatedMax) };
+}
+
+/** Blend read evidence into base confidence: +0..READ_BOOST_MAX, capped at 0.99.
+ *  提权不设门槛（observe-before-enforce：先积累读证据，硬门槛等有生产数据再定）。 */
+export function applyReadBoost(base: number, distinctReaders: number): number {
+  const boost = Math.min(1, distinctReaders / 4) * READ_BOOST_MAX;
+  return Math.min(0.99, base + boost);
+}
+
 // ---------------------------------------------------------------------------
 // Main scan
 // ---------------------------------------------------------------------------
@@ -165,78 +329,150 @@ export async function scanForPromotions(
 ): Promise<PromotionScanResult> {
   const cfg: PromotionConfig = { ...DEFAULT_CONFIG, ...config };
 
-  // 1. Load all entries in scope (high limit to get everything meaningful)
-  const entries = await store.list([scope], undefined, 500, 0);
-  const active = entries.filter(isActive);
+  // 1. Paged full scan, category pushed down to the DB layer.
+  //    旧实现 store.list([scope], undefined, 500, 0) 双重失效:① limit=500 在
+  //    34K+ 库上覆盖率 ~1.4%;② list() 性能优化恒返回 vector:[],聚类全部跳过,
+  //    管线产出恒为零(单测 mock 带向量所以从未暴露)。
+  // cases/patterns 各自独立预算——共享预算时大库的 cases 会把 patterns 饿死
+  // (首次生产 dry-run 实测:20000 cases 拉满后 patterns scanned=0,
+  // pattern_to_skill 通道整个没跑)。
+  const rawCases = await listAllByCategory(store, scope, "cases", cfg.maxScanEntries, cfg.pageSize, 2_000);
+  const rawPatterns = await listAllByCategory(store, scope, "patterns", cfg.maxScanEntries, cfg.pageSize);
 
-  const cases = active.filter(e => e.category === "cases");
-  const patterns = active.filter(e => e.category === "patterns");
+  const cases = rawCases.filter(isActive);
+  const patterns = rawPatterns.filter(isActive);
 
   const result: PromotionScanResult = {
     candidates: [],
     scannedCases: cases.length,
     scannedPatterns: patterns.length,
+    truncatedCases: 0,
+    vectorlessSkipped: 0,
   };
 
-  // 2. Cluster cases by vector similarity
+  // 2. Cluster cases bucket-by-bucket (topicTag, untagged fallback)。
+  //    向量按桶回填、桶毕即释,全库向量绝不常驻;分桶同时把 greedyCluster 的
+  //    最坏 O(n²) 限制在 maxBucketSize 内。
+  //    配额 per-channel:case 通道最多产 maxCandidates 个,pattern 通道同;
+  //    最后合并按 confidence 排序截断——否则 case 候选多的库会让
+  //    pattern_to_skill 通道在全局 break 处永远轮空(首次生产 dry-run 实测)。
+  let caseCandidates = 0;
   if (cases.length >= cfg.minCaseOccurrences) {
-    const clusters = greedyCluster(cases, cfg.caseSimilarityThreshold);
-
-    for (const cluster of clusters) {
-      if (cluster.members.length < cfg.minCaseOccurrences) continue;
-      if (result.candidates.length >= cfg.maxCandidates) break;
-
-      // Compute average intra-cluster similarity for scoring
-      const avgSim = computeAverageIntraClusterSimilarity(cluster.members);
-
-      result.candidates.push({
-        type: "case_to_pattern",
-        sourceEntries: cluster.members.map(m => ({
-          id: m.id,
-          text: m.text,
-          score: avgSim,
-        })),
-        suggestedName: extractName(cluster.seed.text),
-        suggestedDescription: summarizeCluster(cluster.members),
-        confidence: cluster.members.length / (cluster.members.length + 2), // Bayesian smoothing
-      });
+    const { buckets, truncated } = bucketByTopic(cases, cfg.maxBucketSize);
+    result.truncatedCases = truncated;
+
+    for (const bucket of buckets.values()) {
+      if (bucket.length < cfg.minCaseOccurrences) continue;
+      if (caseCandidates >= cfg.maxCandidates) break;
+
+      const vectorMap = await store.getVectors(bucket.map(e => e.id));
+      const withVectors = bucket
+        .map(e => ({ ...e, vector: vectorMap.get(e.id) ?? [] }))
+        .filter(e => e.vector.length > 0);
+      result.vectorlessSkipped += bucket.length - withVectors.length;
+      if (withVectors.length < cfg.minCaseOccurrences) continue;
+
+      const clusters = greedyCluster(withVectors, cfg.caseSimilarityThreshold);
+
+      for (const cluster of clusters) {
+        if (cluster.members.length < cfg.minCaseOccurrences) continue;
+        if (caseCandidates >= cfg.maxCandidates) break;
+
+        // Compute average intra-cluster similarity for scoring
+        const avgSim = computeAverageIntraClusterSimilarity(cluster.members);
+
+        caseCandidates++;
+        const caseReadEvidence = aggregateReadEvidence(cluster.members);
+        result.candidates.push({
+          type: "case_to_pattern",
+          sourceEntries: cluster.members.map(m => ({
+            id: m.id,
+            text: m.text,
+            score: avgSim,
+          })),
+          suggestedName: extractName(cluster.seed.text),
+          suggestedDescription: summarizeCluster(cluster.members),
+          confidence: applyReadBoost(
+            cluster.members.length / (cluster.members.length + 2), // Bayesian smoothing
+            caseReadEvidence.distinctReaders,
+          ),
+          readEvidence: caseReadEvidence,
+        });
+      }
     }
   }
 
-  // 3. Detect pattern_to_skill candidates
-  for (const pattern of patterns) {
-    if (result.candidates.length >= cfg.maxCandidates) break;
-    if (!hasStructuredSteps(pattern.text)) continue;
-    if (!pattern.vector?.length) continue;
-
-    // Find cases similar to this pattern
-    const similarCases = cases.filter(c => {
-      if (!c.vector?.length) return false;
-      const sim = cosineSimilarity(pattern.vector, c.vector);
-      return sim >= cfg.caseSimilarityThreshold;
-    });
+  // 3. Detect pattern_to_skill candidates — similarity search pushed down to the
+  //    vector index (one vectorSearch per structured pattern) instead of pairwise
+  //    cosine against the full in-memory case corpus.
+  //    vectorSearch score = 1/(1+cosineDistance) = 1/(2-cosineSim) is monotonic in
+  //    cosineSim, so minScore = 1/(2-threshold) filters EXACTLY the same set as
+  //    `cosineSim >= threshold`; per-hit cosine 反算 = 2 - 1/score.
+  const structuredPatterns = patterns
+    .filter(p => hasStructuredSteps(p.text))
+    .sort((a, b) => (b.timestamp || 0) - (a.timestamp || 0))
+    .slice(0, cfg.maxPatternProbes);
+  const patternVectors = structuredPatterns.length > 0
+    ? await store.getVectors(structuredPatterns.map(p => p.id))
+    : new Map<string, number[]>();
+  const minSearchScore = 1 / (2 - cfg.caseSimilarityThreshold);
+
+  let patternCandidates = 0;
+  for (const pattern of structuredPatterns) {
+    if (patternCandidates >= cfg.maxCandidates) break;
+    const vec = patternVectors.get(pattern.id);
+    if (!vec || vec.length === 0) {
+      result.vectorlessSkipped++;
+      continue;
+    }
+
+    const hits = await store.vectorSearch(vec, 20, minSearchScore, [scope]);
+    const similarCases = hits.filter(
+      h => h.entry.category === "cases" && h.entry.id !== pattern.id && isActive(h.entry),
+    );
 
     if (similarCases.length < 2) continue;
 
+    // A2: zero-LLM verifier — pattern 当 draft，supporting cases 当 evidence。
+    // steps 传 [] 不是漏传：pattern.text 已含完整 Steps 块，resonance 用整段文本即可；
+    // extractSteps(pattern.text) 仅用于下面的 suggestedImplementation 字段。
+    const verification = verifyDraft(
+      { tools: extractToolsFromEntry(pattern), summary: pattern.text, steps: [] },
+      similarCases.map(h => ({ text: h.entry.text, tools: extractToolsFromEntry(h.entry) })),
+    );
+
+    patternCandidates++;
+    const patternReadEvidence = aggregateReadEvidence([pattern, ...similarCases.map(h => h.entry)]);
     result.candidates.push({
       type: "pattern_to_skill",
       sourceEntries: [
         { id: pattern.id, text: pattern.text, score: 1.0 },
-        ...similarCases.map(c => ({
-          id: c.id,
-          text: c.text,
-          score: cosineSimilarity(pattern.vector, c.vector),
+        ...similarCases.map(h => ({
+          id: h.entry.id,
+          text: h.entry.text,
+          score: 2 - 1 / h.score, // back-convert to cosine similarity
         })),
       ],
       suggestedName: extractName(pattern.text),
       suggestedDescription: `Skill derived from pattern with ${similarCases.length} supporting cases`,
       suggestedImplementation: extractSteps(pattern.text),
-      confidence: similarCases.length / (similarCases.length + 2),
+      confidence: applyReadBoost(
+        similarCases.length / (similarCases.length + 2),
+        patternReadEvidence.distinctReaders,
+      ),
+      verification,
+      readEvidence: patternReadEvidence,
     });
   }
 
-  // Sort by confidence descending, then truncate
-  result.candidates.sort((a, b) => b.confidence - a.confidence);
+  // Sort: A2 verifier-passed first, then confidence desc, then truncate.
+  // 失败候选保留披露但排后；截断优先砍失败候选，通过的不被挤掉(Codex 验证补充)。
+  result.candidates.sort((a, b) => {
+    const aOk = a.verification?.ok ?? true;
+    const bOk = b.verification?.ok ?? true;
+    if (aOk !== bOk) return aOk ? -1 : 1;
+    return b.confidence - a.confidence;
+  });
   result.candidates = result.candidates.slice(0, cfg.maxCandidates);
 
   return result;
@@ -252,6 +488,14 @@ export function formatPromotionResult(result: PromotionScanResult): string {
     `Promotion scan: ${result.scannedCases} cases, ${result.scannedPatterns} patterns scanned.`,
   ];
 
+  // No-silent-caps:截断与向量缺失必须可见,否则"0 候选"会被误读成"扫全了没东西"。
+  if (result.truncatedCases > 0) {
+    lines.push(`⚠️ ${result.truncatedCases} cases truncated by bucket cap (kept most recent per topic bucket).`);
+  }
+  if (result.vectorlessSkipped > 0) {
+    lines.push(`⚠️ ${result.vectorlessSkipped} entries skipped (no vector in store).`);
+  }
+
   if (result.candidates.length === 0) {
     lines.push("No promotion candidates found.");
     return lines.join("\n");
@@ -264,6 +508,18 @@ export function formatPromotionResult(result: PromotionScanResult): string {
     lines.push(`Confidence: ${(c.confidence * 100).toFixed(1)}%`);
     lines.push(`Description: ${c.suggestedDescription}`);
     lines.push(`Sources: ${c.sourceEntries.length} entries`);
+    if (c.readEvidence) {
+      lines.push(`Read evidence: ${c.readEvidence.totalAccess} total reads, ${c.readEvidence.distinctReaders} distinct reader(s)`);
+    }
+    if (c.verification) {
+      const v = c.verification;
+      if (v.ok) {
+        lines.push(`Verifier: ✓ pass (coverage ${(v.coverage * 100).toFixed(0)}%, resonance ${(v.resonance * 100).toFixed(0)}%)`);
+      } else {
+        const unmapped = v.unmappedTools.length > 0 ? `; unmapped tools: ${v.unmappedTools.join(", ")}` : "";
+        lines.push(`Verifier: ⚠️ FAILED — ${v.reason ?? "?"} (coverage ${(v.coverage * 100).toFixed(0)}%, resonance ${(v.resonance * 100).toFixed(0)}%${unmapped})`);
+      }
+    }
     if (c.suggestedImplementation) {
       lines.push(`Implementation:\n\`\`\`\n${c.suggestedImplementation}\n\`\`\``);
     }

package/src/skill-schema.ts

@@ -1,14 +1,27 @@
 /**
- * D-1: Skill Schema — defines the shape of executable skills stored in memory.
+ * D-1: Skill Schema — defines the shape of agent-readable skill runbooks stored in memory.
  *
  * Skills are "what an agent can do" (vs. memories which are "what an agent learned").
  * Alita/Alita-G showed MCP itself is a natural skill representation format.
+ *
+ * v2.5 (2026-05-27) — schema 收缩：
+ * 原 SkillImplementationTypeSchema 含 "bash" / "python" / "mcp_tool_chain" / "instruction_sequence"
+ * 四种，**implementation 字段从未真执行**（无 evaluator，仅作 context 给 agent 读）——是 schema
+ * 撒谎暗示可执行。源自 brgsk《agent memory: an anatomy》借鉴审计 + Codex trio 二审建议
+ * "P1 选收缩/删承诺，不接 evaluator"。
+ *
+ * 现在 enum 只保留 "instruction_sequence" 唯一类型，明确 skill 是 **agent-readable runbook**
+ * 而非可执行物。未来如真接 evaluator（产品决策另开），再展开 enum 加 "bash" / "python" 等。
+ *
+ * 兼容性：parseSkillFromEntry 读取老 metadata 用 type cast 不走 schema 校验，所以历史 bash/python
+ * skill records 仍可 retrieve；只是新写入受新 schema 约束。production 库 2026-05-27 实测无真实
+ * skill 数据，破坏面接近 zero。
  */
 
 import { z } from "zod";
 
 export const SkillImplementationTypeSchema = z.enum([
-  "bash", "python", "mcp_tool_chain", "instruction_sequence",
+  "instruction_sequence",
 ]);
 
 export type SkillImplementationType = z.infer<typeof SkillImplementationTypeSchema>;
@@ -18,7 +31,7 @@ export const SkillInputSchema = z.object({
   description: z.string().min(1).max(500).describe("Natural language description (used for retrieval)"),
   triggerPattern: z.string().min(1).max(300).describe("When to suggest this skill"),
   implementationType: SkillImplementationTypeSchema,
-  implementation: z.string().min(1).max(5000).describe("Executable content"),
+  implementation: z.string().min(1).max(5000).describe("Agent-readable runbook content: markdown steps, natural language workflow, or structured procedure. RecallNest does NOT execute this — it stores runbooks for agents to read and follow as context."),
   inputSchema: z.record(z.string(), z.unknown()).optional().describe("Parameter definition (JSON Schema)"),
   verification: z.string().max(500).optional().describe("How to verify execution success"),
   scope: z.string().min(1).max(160).describe("Project scope"),

package/src/skill-verifier.ts

@@ -0,0 +1,152 @@
+/**
+ * A2 · Skill promotion verifier — zero-LLM consistency gate.
+ *
+ * 借鉴 MemOS local-plugin `core/skill/verifier.ts`（repo-insight 借鉴审计 2026-06-13）。
+ * 用在 `scan_skill_promotions` 的 pattern_to_skill 候选生成处：pattern 当 draft，
+ * supporting cases 当 evidence。两个确定性检查，**无 LLM 调用**：
+ *
+ * 1. **tool coverage**：draft 声称的 tools 必须 ⊆ evidence 里真实出现过的 tools
+ *    （覆盖率 ≥ COVERAGE_THRESHOLD）。专治 LLM 蒸馏 skill 时编造证据里没有的命令/工具名。
+ * 2. **evidence resonance**：≥ minResonance 比例的 evidence 与 draft 的 summary/steps
+ *    共享 ≥2 个 token。专治"叙述跟例子对不上"。
+ *
+ * `tokensOf` 对中文做 2-gram bigram（RecallNest case/skill 大量中文，不能只认 ASCII token）。
+ * verdict 只描述、不决策——调用方（skill-promotion）据此附 `verification` 字段披露，
+ * 失败候选保留排后、不静默丢弃（no-silent-caps）。
+ */
+
+export interface VerifyDraft {
+  /** draft 声称用到的工具/命令名 */
+  tools: string[];
+  /** draft 摘要文本（如 pattern 的 title + trigger / 正文） */
+  summary: string;
+  /** draft 步骤文本 */
+  steps: string[];
+}
+
+export interface VerifyEvidence {
+  /** 证据条目正文（如 supporting case 的 text） */
+  text: string;
+  /** 证据条目里真实出现过的工具/命令名 */
+  tools: string[];
+}
+
+export interface VerifyResult {
+  ok: boolean;
+  /** draft.tools ∩ evidenceTools / draft.tools（无声称工具时为 1） */
+  coverage: number;
+  /** 与 draft 共享 ≥2 token 的 evidence 比例 */
+  resonance: number;
+  /** draft 声称但任何 evidence 都没出现过的工具（疑似幻觉） */
+  unmappedTools: string[];
+  /** 失败原因；ok=true 时省略 */
+  reason?: string;
+}
+
+export const DEFAULT_MIN_RESONANCE = 0.5;
+export const COVERAGE_THRESHOLD = 0.5;
+
+/**
+ * 对一份 draft + 其证据做零 LLM 一致性校验。确定性、可单测、读写无副作用。
+ */
+export function verifyDraft(
+  draft: VerifyDraft,
+  evidence: VerifyEvidence[],
+  options: { minResonance?: number } = {},
+): VerifyResult {
+  const minResonance = options.minResonance ?? DEFAULT_MIN_RESONANCE;
+
+  if (evidence.length === 0) {
+    return { ok: false, coverage: 0, resonance: 0, unmappedTools: [], reason: "no-evidence" };
+  }
+
+  // --- tool coverage（集合包含检查）---
+  const evidenceTools = new Set<string>();
+  for (const ev of evidence) {
+    for (const t of ev.tools) {
+      const norm = t.trim().toLowerCase();
+      if (norm) evidenceTools.add(norm);
+    }
+  }
+  const draftTools = draft.tools.map((t) => t.trim().toLowerCase()).filter(Boolean);
+  const matched: string[] = [];
+  const unmapped: string[] = [];
+  for (const tok of draftTools) {
+    if (evidenceTools.has(tok)) matched.push(tok);
+    else unmapped.push(tok);
+  }
+  // 无声称工具 → 无可证伪，coverage 视为满分（只看 resonance）。
+  const coverage = draftTools.length === 0 ? 1 : matched.length / draftTools.length;
+
+  // --- evidence resonance ---
+  const resonance = computeResonance(draft, evidence);
+
+  if (coverage < COVERAGE_THRESHOLD && draftTools.length > 0) {
+    return {
+      ok: false,
+      coverage,
+      resonance,
+      unmappedTools: unmapped,
+      reason: `coverage=${coverage.toFixed(2)}<${COVERAGE_THRESHOLD}`,
+    };
+  }
+  if (resonance < minResonance) {
+    return {
+      ok: false,
+      coverage,
+      resonance,
+      unmappedTools: unmapped,
+      reason: `resonance=${resonance.toFixed(2)}<${minResonance}`,
+    };
+  }
+  return { ok: true, coverage, resonance, unmappedTools: unmapped };
+}
+
+function computeResonance(draft: VerifyDraft, evidence: VerifyEvidence[]): number {
+  const needle = [draft.summary, ...draft.steps].join(" ").toLowerCase();
+  const draftTokens = tokensOf(needle);
+  if (draftTokens.size === 0) return 0;
+  let hit = 0;
+  for (const ev of evidence) {
+    const toks = tokensOf(ev.text.toLowerCase());
+    let overlap = 0;
+    for (const tok of draftTokens) {
+      if (toks.has(tok)) {
+        overlap += 1;
+        if (overlap >= 2) break; // 只需判定 ≥2，命中即可停
+      }
+    }
+    if (overlap >= 2) hit += 1;
+  }
+  return hit / evidence.length;
+}
+
+/**
+ * 分词：ASCII 标识符（≥4 字符、去停用词）+ CJK 2-gram bigram。
+ * CJK 部分不走停用词（2-gram 本身已足够稀疏）。
+ */
+export function tokensOf(s: string): Set<string> {
+  const out = new Set<string>();
+  const asciiMatches = s.match(/[a-z0-9_][a-z0-9_./-]{3,}/g) ?? [];
+  for (const m of asciiMatches) {
+    const tok = m.toLowerCase();
+    if (RESONANCE_STOPWORDS.has(tok)) continue;
+    out.add(tok);
+  }
+  const cjkRuns = s.match(/[一-鿿぀-ヿ㐀-䶿]{2,}/g) ?? [];
+  for (const run of cjkRuns) {
+    for (let i = 0; i + 1 < run.length; i++) {
+      out.add(run.slice(i, i + 2));
+    }
+  }
+  return out;
+}
+
+const RESONANCE_STOPWORDS = new Set<string>([
+  "the", "and", "for", "with", "that", "this", "from", "will", "then",
+  "into", "when", "what", "where", "your", "user", "agent", "null", "true",
+  "false", "none", "let", "new", "old", "use", "used", "have", "has", "its",
+  "not", "any", "can", "does", "only", "just", "like", "please", "step",
+  "steps", "body", "title", "summary", "task", "tasks", "run", "see", "end",
+  "our", "their", "them", "being", "make", "made", "thing", "things",
+]);