recallnest 2.2.1 → 2.5.4

package/src/connector-types.ts

@@ -0,0 +1,57 @@
+/**
+ * Connector Standard Types (connector-v1)
+ *
+ * 定义外部数据源（Obsidian、Email、RSS、自定义脚本）统一产出的 JSON 格式。
+ * ingest.ts 的 ingestConnectorFile 消费这个格式，走已有的 dedup/extract/入库管线。
+ *
+ * 协议版本管理：version 字段用于未来兼容性。当前固定 "connector-v1"。
+ */
+
+export interface ConnectorOutputV1 {
+  /** 格式版本，固定 "connector-v1" */
+  version: "connector-v1";
+  /** 数据源标识，如 "obsidian", "email", "rss", "x-bookmarks" */
+  source: string;
+  /** 目标 scope，如 "vault:my-notes", "project:research" */
+  scope: string;
+  /** 批次 ID（可选，用于幂等重试） */
+  batchId?: string;
+  /** 产出时间 ISO 8601 */
+  producedAt: string;
+  /** 记录列表 */
+  records: ConnectorRecord[];
+}
+
+export interface ConnectorRecord {
+  /** 记录唯一 ID（source 内唯一，用于增量去重） */
+  id: string;
+  /** 正文 */
+  text: string;
+  /** 标题/heading（可选） */
+  title?: string;
+  /** 分类提示：preferences / events / knowledge / facts / decisions */
+  categoryHint?: string;
+  /** 重要性提示 0-1（可选，默认 0.7） */
+  importanceHint?: number;
+  /** 标签 */
+  tags?: string[];
+  /** 原始时间戳 ISO 8601 */
+  timestamp?: string;
+  /** 内容哈希（用于增量同步，调用方计算） */
+  contentHash?: string;
+  /** 来源元数据（自由字段） */
+  sourceMetadata?: Record<string, unknown>;
+}
+
+/** 运行时格式验证：判定一个 parsed JSON 是否是合法 connector-v1 */
+export function isConnectorOutputV1(value: unknown): value is ConnectorOutputV1 {
+  if (!value || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  return (
+    obj.version === "connector-v1"
+    && typeof obj.source === "string"
+    && typeof obj.scope === "string"
+    && typeof obj.producedAt === "string"
+    && Array.isArray(obj.records)
+  );
+}

package/src/consolidation-engine.ts

@@ -17,7 +17,9 @@
  * LLM-free — deterministic clustering and merge only.
  */
 
-import type { MemoryEntry, MemorySearchResult, MemoryStore } from "./store.js";
+import type { MemoryEntry, MemorySearchResult } from "./store.js";
+import { deterministicId } from "./store.js";
+import type { MemoryStorePort } from "./memory-store-port.js";
 import { createVersionGroup } from "./version-manager.js";
 import { isActiveMemory, parseEvolution, buildSupersedeMetadata, buildConsolidatedMetadata, patchEvolution } from "./memory-evolution.js";
 import { cosineSimilarity } from "./multi-vector.js";
@@ -35,12 +37,22 @@ export interface ConsolidationConfig {
   mergeThreshold: number;
   /** Maximum entries to scan per consolidation run (default 500) */
   maxEntriesPerRun: number;
+  /**
+   * KG evidence: triple-set Jaccard at/above this merges a grey-zone pair
+   * (vector sim between clusterThreshold and mergeThreshold). Default 0.5 —
+   * provisional until calibrated on production data (plan Q3).
+   */
+  tripleJaccardThreshold?: number;
+  /** KG evidence: both sides need at least this many triples to qualify (default 2) */
+  minTriplesForEvidence?: number;
 }
 
 export const DEFAULT_CONSOLIDATION_CONFIG: ConsolidationConfig = {
   clusterThreshold: 0.82,
   mergeThreshold: 0.92,
   maxEntriesPerRun: 500,
+  tripleJaccardThreshold: 0.5,
+  minTriplesForEvidence: 2,
 };
 
 export interface ConflictEvent {
@@ -54,10 +66,52 @@ export interface ConsolidationResult {
   clustersFound: number;
   mergedCount: number;
   relationsAdded: number;
+  /** Of mergedCount, how many were below mergeThreshold and merged on KG triple evidence */
+  tripleEvidenceMerges: number;
   conflictsDetected: ConflictEvent[];
   scope: string;
 }
 
+// ---------------------------------------------------------------------------
+// KG evidence source (duck-typed subset of KGStore)
+// ---------------------------------------------------------------------------
+
+/** The two triple fields consolidation needs — structurally satisfied by KGTriple. */
+export interface ConsolidationTripleEvidence {
+  id: string;
+  mention_count: number;
+}
+
+export interface ConsolidationKGSource {
+  getTriplesBySourceMemories(memoryIds: string[]): Promise<Map<string, ConsolidationTripleEvidence[]>>;
+}
+
+/**
+ * Jaccard overlap of two triple-id sets. Below `minSize` on either side the
+ * evidence is considered too weak and 0 is returned (a single shared triple
+ * must not merge two memories on its own).
+ */
+export function tripleJaccard(
+  a: ReadonlySet<string> | undefined,
+  b: ReadonlySet<string> | undefined,
+  minSize = 2,
+): number {
+  if (!a || !b || a.size < minSize || b.size < minSize) return 0;
+  let inter = 0;
+  for (const x of a) if (b.has(x)) inter++;
+  return inter / (a.size + b.size - inter);
+}
+
+/**
+ * Mention-frequency boost in canonical selection: tie-breaker ONLY, never an
+ * override of a clear canonicalScore gap (an entry with one hot triple must
+ * not demote a substantially more important memory to consolidated status).
+ * α=0.06 keeps the boost differentiating (m=1 → 1.042, m=9 → 1.138) while the
+ * 1.1 cap bounds the maximum flip at ~10% of the base score — effectively ties.
+ */
+const MENTION_ALPHA = 0.06;
+const MENTION_BOOST_CAP = 1.1;
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -108,7 +162,7 @@ export function detectHeuristicContradiction(textA: string, textB: string): bool
 // Store interface (duck-typed to avoid hard dependency)
 // ---------------------------------------------------------------------------
 
-type ConsolidationStore = Pick<MemoryStore, "list" | "getById" | "vectorSearch" | "update">;
+type ConsolidationStore = Pick<MemoryStorePort, "list" | "getById" | "vectorSearch" | "update">;
 
 // ---------------------------------------------------------------------------
 // Engine
@@ -118,17 +172,25 @@ export class ConsolidationEngine {
   constructor(
     private store: ConsolidationStore,
     private config: ConsolidationConfig = DEFAULT_CONSOLIDATION_CONFIG,
+    /** Optional KG evidence source — absent = pure vector behavior, unchanged */
+    private kgSource: ConsolidationKGSource | null = null,
   ) {}
 
   async run(scope: string): Promise<ConsolidationResult> {
-    const { clusterThreshold, mergeThreshold, maxEntriesPerRun } = this.config;
+    const {
+      clusterThreshold,
+      mergeThreshold,
+      maxEntriesPerRun,
+      tripleJaccardThreshold = 0.5,
+      minTriplesForEvidence = 2,
+    } = this.config;
 
     // 1. Fetch entries in scope
     const entries = await this.store.list([scope], undefined, maxEntriesPerRun, 0);
     const active = entries.filter(isActive);
 
     if (active.length === 0) {
-      return { originalCount: 0, clustersFound: 0, mergedCount: 0, relationsAdded: 0, conflictsDetected: [], scope };
+      return { originalCount: 0, clustersFound: 0, mergedCount: 0, relationsAdded: 0, tripleEvidenceMerges: 0, conflictsDetected: [], scope };
     }
 
     // 2. Group by category
@@ -142,6 +204,7 @@ export class ConsolidationEngine {
     let clustersFound = 0;
     let mergedCount = 0;
     let relationsAdded = 0;
+    let tripleEvidenceMerges = 0;
     const conflictsDetected: ConflictEvent[] = [];
 
     // 3. Cluster within each category
@@ -183,8 +246,27 @@ export class ConsolidationEngine {
         }
         if (memberEntries.length < 2) continue;
 
-        // Determine canonical: highest canonicalScore
-        const sorted = [...memberEntries].sort((a, b) => canonicalScore(b) - canonicalScore(a));
+        // KG triple evidence for this cluster (single batch query; best-effort —
+        // on failure consolidation proceeds vector-only)
+        const tripleIdsByMember = new Map<string, Set<string>>();
+        const maxMentionByMember = new Map<string, number>();
+        if (this.kgSource) {
+          try {
+            const triplesByMember = await this.kgSource.getTriplesBySourceMemories(memberEntries.map(e => e.id));
+            for (const [mid, triples] of triplesByMember) {
+              tripleIdsByMember.set(mid, new Set(triples.map(t => t.id)));
+              maxMentionByMember.set(mid, triples.reduce((m, t) => Math.max(m, t.mention_count), 0));
+            }
+          } catch { /* KG evidence is best-effort */ }
+        }
+
+        // Determine canonical: highest canonicalScore, frequency-boosted when
+        // KG evidence exists (memories carrying often-mentioned facts win ties)
+        const mentionBoost = (e: MemoryEntry) =>
+          Math.min(MENTION_BOOST_CAP, 1 + MENTION_ALPHA * Math.log((maxMentionByMember.get(e.id) ?? 0) + 1));
+        const sorted = [...memberEntries].sort(
+          (a, b) => canonicalScore(b) * mentionBoost(b) - canonicalScore(a) * mentionBoost(a),
+        );
         const canonical = sorted[0];
 
         if (!canonical.vector?.length) continue;
@@ -199,7 +281,16 @@ export class ConsolidationEngine {
         for (const member of sorted.slice(1)) {
           const sim = scoreMap.get(member.id) ?? clusterThreshold;
 
-          if (sim >= mergeThreshold) {
+          // Second evidence source: two memories whose extracted fact sets
+          // overlap heavily are duplicates even when vector sim sits in the
+          // grey zone (the "pairwise near-duplicates" the 0.92 bar misses).
+          const jaccard = tripleJaccard(
+            tripleIdsByMember.get(canonical.id),
+            tripleIdsByMember.get(member.id),
+            minTriplesForEvidence,
+          );
+
+          if (sim >= mergeThreshold || jaccard >= tripleJaccardThreshold) {
             // Tier 3.3: Version coexistence — both stay but grouped.
             await createVersionGroup(this.store, canonical, member, scope);
             // C-1: Also mark the weaker entry as consolidated via evolution metadata
@@ -214,6 +305,7 @@ export class ConsolidationEngine {
               await this.store.update(canonical.id, { metadata: updatedCanon }, [scope]);
             }
             mergedCount++;
+            if (sim < mergeThreshold) tripleEvidenceMerges++;
           } else {
             // Link: add clustered_with relation
             const memberMeta = parseMetadata(member);
@@ -245,7 +337,7 @@ export class ConsolidationEngine {
       }
     }
 
-    return { originalCount: active.length, clustersFound, mergedCount, relationsAdded, conflictsDetected, scope };
+    return { originalCount: active.length, clustersFound, mergedCount, relationsAdded, tripleEvidenceMerges, conflictsDetected, scope };
   }
 }
 
@@ -278,7 +370,7 @@ export async function clusterAndConsolidate(params: {
   entries: MemoryEntry[];
   embedder: Pick<Embedder, "embedPassage">;
   llm: LLMClient;
-  store: Pick<MemoryStore, "store" | "update">;
+  store: Pick<MemoryStorePort, "store" | "update">;
   scope: string;
   /** Minimum cluster size to trigger consolidation (default: 3) */
   minClusterSize?: number;
@@ -400,8 +492,13 @@ export async function clusterAndConsolidate(params: {
     // Embed the insight text
     const insightVector = await params.embedder.embedPassage(insight);
 
-    // Store the insight as a new memory
+    // Store the insight as a new memory. P0-2/P1-2: derive a deterministic id from the
+    // (sorted) source member ids so re-running dream/consolidate on the same cluster
+    // upserts the same insight row instead of appending a near-duplicate each run
+    // (the highest-frequency dup-id source). Cross-run stable because sourceIds are stable.
+    const sortedSourceIds = cluster.map(m => m.id).slice().sort();
     const insightEntry = await store.store({
+      id: deterministicId(scope, `cluster-insight:${sortedSourceIds.join(",")}`),
       text: insight,
       vector: insightVector,
       category: bestCat,
@@ -444,6 +541,7 @@ export async function clusterAndConsolidate(params: {
         const patternImportance = Math.min(maxImportance + 0.1, 1.0);
         const patternVector = await params.embedder.embedPassage(patternText);
         const patternEntry = await store.store({
+          id: deterministicId(scope, `cluster-pattern:${sortedSourceIds.join(",")}`),
           text: patternText,
           vector: patternVector,
           category: "patterns",
@@ -492,7 +590,7 @@ export function formatConsolidationResult(result: ConsolidationResult): string {
     `Consolidation complete for scope: ${result.scope}`,
     `Scanned: ${result.originalCount} active entries`,
     `Clusters found: ${result.clustersFound}`,
-    `Merged (versioned): ${result.mergedCount}`,
+    `Merged (versioned): ${result.mergedCount}${result.tripleEvidenceMerges > 0 ? ` (${result.tripleEvidenceMerges} on triple evidence)` : ""}`,
     `Relations added: ${result.relationsAdded}`,
     `Conflicts detected: ${result.conflictsDetected.length}`,
   ];

package/src/context-composer.ts

@@ -1,4 +1,5 @@
 import { listPinAssets, type PinAsset } from "./memory-assets.js";
+import * as envConfig from "./env-config.js";
 import { buildStableContextSections } from "./context-composer-stable.js";
 import {
   buildAssociativeNestEntityFallbackQuery,
@@ -32,6 +33,8 @@ type ResumeCategory = "profile" | "preferences" | "entities" | "patterns" | "cas
 
 interface ResumeRetriever {
   retrieve(context: RetrievalContext): Promise<RetrievalResult[]>;
+  /** Optional: 影子记录 resume reconstruction 引用的记忆（injection-vs-use）。未实现则 no-op。 */
+  recordReconstructionUsage?(citedIds: string[]): Promise<void>;
 }
 
 interface CheckpointLookup {
@@ -467,7 +470,7 @@ export async function composeResumeContext(
   let reconstructedContext: string | undefined;
   let reconstructionConfidence: number | undefined;
   let reconstructionContradictions: Array<{ memoryIds: [string, string]; description: string }> | undefined;
-  const constructiveFlag = process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL === "true";
+  const constructiveFlag = envConfig.constructiveRetrieval();
   if (constructiveFlag && deps.llm?.isAvailable?.()) {
     const allReconResults = [...profileResults, ...preferenceResults, ...entityResults, ...filteredPatterns, ...filteredCases];
     if (allReconResults.length >= 3) {
@@ -489,6 +492,10 @@ export async function composeResumeContext(
         if (recon.contradictions.length > 0) {
           reconstructionContradictions = recon.contradictions;
         }
+        // Shadow usage：resume reconstruction 真正引用的记忆记 use 计数（不动 ranking/forget）。
+        if (recon.sources.length > 0) {
+          await deps.retriever.recordReconstructionUsage?.(recon.sources.map(s => s.id));
+        }
       } catch { /* silent fallback */ }
     }
   }

package/src/conversation-importer.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import type { PersistMemoryDeps } from "./capture-engine.js";
 import { persistMemory } from "./capture-engine.js";
 import type { StoredMemoryRecord } from "./memory-schema.js";
+import { isConnectorOutputV1, type ConnectorOutputV1 } from "./connector-types.js";
 
 export interface NormalizedMessage {
   role: "user" | "assistant" | "system";
@@ -14,7 +15,8 @@ export type ConversationFormat =
   | "claude-ai"
   | "chatgpt"
   | "slack"
-  | "plaintext";
+  | "plaintext"
+  | "connector-v1";
 
 // ---------------------------------------------------------------------------
 // Format detection
@@ -40,6 +42,10 @@ export function detectFormat(content: string): ConversationFormat {
       }
 
       if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        // connector-v1: highest priority — explicit version tag
+        if (isConnectorOutputV1(parsed)) {
+          return "connector-v1";
+        }
         if (parsed.chat_conversations !== undefined) {
           return "claude-ai";
         }
@@ -366,6 +372,22 @@ export function normalizePlaintext(content: string): NormalizedMessage[] {
   return messages;
 }
 
+// ---------------------------------------------------------------------------
+// Connector-v1 normalizer
+// ---------------------------------------------------------------------------
+
+export function normalizeConnectorV1(content: string): NormalizedMessage[] {
+  const parsed: ConnectorOutputV1 = JSON.parse(content);
+  if (!isConnectorOutputV1(parsed)) {
+    throw new Error("Invalid connector-v1 format: missing version/source/scope/records");
+  }
+  return parsed.records.map((r) => ({
+    role: "user" as const,
+    content: r.title ? `[${r.title}] ${r.text}` : r.text,
+    ...(r.timestamp ? { timestamp: r.timestamp } : {}),
+  }));
+}
+
 // ---------------------------------------------------------------------------
 // Unified normalize dispatcher
 // ---------------------------------------------------------------------------
@@ -382,6 +404,8 @@ export function normalizeConversation(content: string, format: ConversationForma
       return normalizeSlack(content);
     case "plaintext":
       return normalizePlaintext(content);
+    case "connector-v1":
+      return normalizeConnectorV1(content);
   }
 }
 

package/src/data-checkup.ts

@@ -15,6 +15,8 @@
 import type { MemoryEntry, MemoryStore } from "./store.js";
 import { resolveTier, type MemoryTier } from "./decay-engine.js";
 import { measureInterferenceDensity } from "./interference-detector.js";
+import { readHeartbeats, checkSourceStaleness, formatAge } from "./source-heartbeat.js";
+import { deriveUsageStatus, isUsageSignalActive, type UsageStatus } from "./usage-tracker.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -29,6 +31,8 @@ export interface CheckResult {
 export interface CheckupReport {
   checks: CheckResult[];
   totalEntries: number;
+  /** Total entries in store; when > totalEntries, only the most recent were scanned. */
+  totalAvailable: number;
   timestamp: string;
 }
 
@@ -38,15 +42,33 @@ export interface CheckupReport {
 
 /** Check 1: All vectors should have the same dimension. */
 function checkVectorDimensions(entries: MemoryEntry[]): CheckResult {
+  // 只对真正取到向量的条目判维度一致性;取不到向量的(dim=0)单独计数后跳过——
+  // 否则会把"未补到向量"误报成"维度不一致",或把"全 0 维空向量"假报成健康。
   const dims = new Map<number, number>(); // dim → count
+  let missingVectors = 0;
   for (const e of entries) {
     const d = e.vector?.length ?? 0;
+    if (d === 0) { missingVectors++; continue; }
     dims.set(d, (dims.get(d) ?? 0) + 1);
   }
 
-  if (dims.size <= 1) {
+  const withVectors = entries.length - missingVectors;
+  if (entries.length === 0) {
+    return { name: "vector_dimensions", status: "ok", detail: "No entries to check" };
+  }
+  if (withVectors === 0) {
+    return {
+      name: "vector_dimensions",
+      status: "warning",
+      detail: `No retrievable vectors among ${entries.length} entries — dimension consistency not verified`,
+    };
+  }
+
+  const suffix = missingVectors > 0 ? ` (${missingVectors} without retrievable vector, skipped)` : "";
+
+  if (dims.size === 1) {
     const dim = dims.keys().next().value ?? 0;
-    return { name: "vector_dimensions", status: "ok", detail: `All ${entries.length} entries have dimension ${dim}` };
+    return { name: "vector_dimensions", status: "ok", detail: `All ${withVectors} vectors have dimension ${dim}${suffix}` };
   }
 
   const sorted = [...dims.entries()].sort((a, b) => b[1] - a[1]);
@@ -55,7 +77,7 @@ function checkVectorDimensions(entries: MemoryEntry[]): CheckResult {
   return {
     name: "vector_dimensions",
     status: "error",
-    detail: `${mismatched} entries have wrong dimension (expected ${expected}): ${sorted.map(([d, c]) => `dim=${d}: ${c}`).join(", ")}`,
+    detail: `${mismatched} entries have wrong dimension (expected ${expected}): ${sorted.map(([d, c]) => `dim=${d}: ${c}`).join(", ")}${suffix}`,
   };
 }
 
@@ -151,7 +173,33 @@ function checkVersionGroups(entries: MemoryEntry[]): CheckResult {
   };
 }
 
-/** Check 6 (F2): Interference density — detect semantic clustering pressure. */
+/** Check 6 (GB-3): Source health — detect stale connector data sources. */
+function checkSourceHealth(heartbeatPath?: string): CheckResult {
+  const heartbeats = readHeartbeats(heartbeatPath);
+  const sources = Object.values(heartbeats);
+  if (sources.length === 0) {
+    return { name: "source_health", status: "ok", detail: "No connector sources tracked yet" };
+  }
+
+  const stale30 = checkSourceStaleness(30, heartbeatPath);
+  const stale7 = checkSourceStaleness(7, heartbeatPath);
+
+  const summary = sources
+    .map((s) => `${s.source}: ${formatAge(s.lastIngest)}`)
+    .join(", ");
+
+  if (stale30.length > 0) {
+    const names = stale30.map((s) => `${s.source} (${s.daysSince}d)`).join(", ");
+    return { name: "source_health", status: "error", detail: `${summary} — critically stale: ${names}` };
+  }
+  if (stale7.length > 0) {
+    const names = stale7.map((s) => `${s.source} (${s.daysSince}d)`).join(", ");
+    return { name: "source_health", status: "warning", detail: `${summary} — stale: ${names}` };
+  }
+  return { name: "source_health", status: "ok", detail: `All sources fresh: ${summary}` };
+}
+
+/** Check 7 (F2): Interference density — detect semantic clustering pressure. */
 function checkInterferenceDensity(entries: MemoryEntry[]): CheckResult {
   // Only check entries with vectors (skip schema/empty entries)
   const withVectors = entries.filter(e => e.vector && e.vector.length > 0);
@@ -189,13 +237,78 @@ function checkInterferenceDensity(entries: MemoryEntry[]): CheckResult {
 // Main
 // ---------------------------------------------------------------------------
 
+/** Check 8 (P0 B-1 观察): usage 四档分布 — injection-vs-use 影子统计的离线观察口。
+ *  纯报告,不接任何决策;cold = 被反复 surface(accessCount≥6)却从未被
+ *  reconstruction 引用,是第二阶段 decay 联动前要先观察校准的核心对象。 */
+function checkUsageDistribution(entries: MemoryEntry[]): CheckResult {
+  // use 信号未采集时(reconstruction flag 关),useCount 恒零 → "cold" 全是假阳性。
+  // 如实报告信号缺失,不输出不可解释的判定。
+  if (!isUsageSignalActive()) {
+    return {
+      name: "usage_distribution",
+      status: "ok",
+      detail: "use signal inactive (RECALLNEST_CONSTRUCTIVE_RETRIEVAL off) — useCount 无写入路径,cold/warm/hot 不可判,统计跳过。该 flag 因合成召回缺失被 Alice 主动关闭(2026-06-11),usage 线搁置中。",
+    };
+  }
+
+  const counts: Record<UsageStatus, number> = { unused: 0, cold: 0, warm: 0, hot: 0 };
+  const coldSamples: Array<{ id: string; injection: number; ageDays: number; scope: string }> = [];
+  const now = Date.now();
+
+  for (const e of entries) {
+    const status = deriveUsageStatus(e);
+    counts[status]++;
+    if (status === "cold") {
+      let injection = 0;
+      try {
+        const meta = JSON.parse(e.metadata || "{}") as Record<string, unknown>;
+        injection = typeof meta.accessCount === "number" ? meta.accessCount : 0;
+      } catch { /* keep 0 */ }
+      coldSamples.push({
+        id: e.id.slice(0, 8),
+        injection,
+        ageDays: Math.floor((now - e.timestamp) / 86_400_000),
+        scope: e.scope || "(none)",
+      });
+    }
+  }
+
+  const total = entries.length;
+  const coldPct = total > 0 ? (counts.cold / total) * 100 : 0;
+  const top = coldSamples
+    .sort((a, b) => b.injection - a.injection)
+    .slice(0, 20)
+    .map(s => `${s.id}(inj=${s.injection}, ${s.ageDays}d, ${s.scope})`)
+    .join(", ");
+
+  return {
+    name: "usage_distribution",
+    status: coldPct > 10 ? "warning" : "ok",
+    detail:
+      `unused=${counts.unused} cold=${counts.cold} (${coldPct.toFixed(1)}%) ` +
+      `warm=${counts.warm} hot=${counts.hot}` +
+      (coldSamples.length > 0 ? `; cold top-${Math.min(20, coldSamples.length)}: ${top}` : ""),
+  };
+}
+
 export interface CheckupDeps {
-  store: Pick<MemoryStore, "list" | "stats">;
+  store: Pick<MemoryStore, "list" | "stats" | "getVectors">;
   openConflictCount: number;
+  /** Optional override path for source-heartbeat.json (used in tests). */
+  heartbeatPath?: string;
 }
 
 export async function runDataCheckup(deps: CheckupDeps): Promise<CheckupReport> {
-  const entries = await deps.store.list(undefined, undefined, 10000, 0);
+  const SCAN_LIMIT = 10000;
+  const listed = await deps.store.list(undefined, undefined, SCAN_LIMIT, 0);
+
+  // list() 为性能不返回向量(vector: []);维度/干扰检查靠向量,否则把"全 0 维"
+  // 误判成健康、干扰分析永远"样本不足"。补回真实向量再检查。
+  const vectorMap = await deps.store.getVectors(listed.map(e => e.id));
+  const entries = listed.map(e => ({ ...e, vector: vectorMap.get(e.id) ?? [] }));
+
+  // 截断披露:库总量 > 已扫,说明只体检了最近 SCAN_LIMIT 条。
+  const totalAvailable = (await deps.store.stats()).totalCount;
 
   return {
     checks: [
@@ -204,17 +317,23 @@ export async function runDataCheckup(deps: CheckupDeps): Promise<CheckupReport>
       checkTierDistribution(entries),
       checkConflictBacklog(deps.openConflictCount),
       checkVersionGroups(entries),
+      checkSourceHealth(deps.heartbeatPath),
       checkInterferenceDensity(entries),
+      checkUsageDistribution(entries),
     ],
     totalEntries: entries.length,
+    totalAvailable,
     timestamp: new Date().toISOString(),
   };
 }
 
 export function formatCheckupReport(report: CheckupReport): string {
+  const truncationNote = report.totalAvailable > report.totalEntries
+    ? ` (of ${report.totalAvailable} total — only the most recent ${report.totalEntries} analyzed)`
+    : "";
   const lines = [
     `Data Checkup Report (${report.timestamp})`,
-    `Total entries scanned: ${report.totalEntries}`,
+    `Total entries scanned: ${report.totalEntries}${truncationNote}`,
     "",
   ];