recallnest 3.0.0 → 3.0.1

package/src/pivot-evidence.ts

@@ -0,0 +1,128 @@
+import { createHash } from "node:crypto";
+
+import { z } from "zod";
+
+export const PIVOT_EVIDENCE_CONTRACT_VERSION = 1 as const;
+
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+export const EvidenceCoordinateSchema = z.object({
+  sessionId: z.string().min(1).max(200),
+  ordinal: z.number().int().nonnegative(),
+  role: z.enum(["user", "assistant"]),
+  contentDigest: z.string().regex(SHA256_HEX),
+}).strict();
+export type EvidenceCoordinate = z.infer<typeof EvidenceCoordinateSchema>;
+
+export const EvidenceWindowTurnSchema = z.object({
+  ordinal: z.number().int().nonnegative(),
+  role: z.enum(["user", "assistant"]),
+  contentDigest: z.string().regex(SHA256_HEX),
+  evidenceIndexes: z.array(z.number().int().nonnegative()).min(1).max(16),
+}).strict();
+export type EvidenceWindowTurn = z.infer<typeof EvidenceWindowTurnSchema>;
+
+export const EvidenceWindowSchema = z.object({
+  sessionId: z.string().min(1).max(200),
+  startOrdinal: z.number().int().nonnegative(),
+  endOrdinal: z.number().int().nonnegative(),
+  turns: z.array(EvidenceWindowTurnSchema).min(1).max(16),
+}).strict();
+export type EvidenceWindow = z.infer<typeof EvidenceWindowSchema>;
+
+export const PivotEvidenceProvenanceSchema = z.object({
+  evidenceContractVersion: z.literal(PIVOT_EVIDENCE_CONTRACT_VERSION),
+  sourceFingerprint: z.string().regex(SHA256_HEX),
+  anchorCoordinate: EvidenceCoordinateSchema,
+  evidenceWindows: z.array(EvidenceWindowSchema).max(16),
+}).strict();
+export type PivotEvidenceProvenance = z.infer<typeof PivotEvidenceProvenanceSchema>;
+
+export function turnContentDigest(input: {
+  sessionId: string;
+  ordinal: number;
+  role: "user" | "assistant";
+  text: string;
+}): string {
+  const canonical = JSON.stringify({
+    schemaVersion: PIVOT_EVIDENCE_CONTRACT_VERSION,
+    sessionId: input.sessionId,
+    ordinal: input.ordinal,
+    role: input.role,
+    text: input.text.replace(/\u0000/g, "").trim(),
+  });
+  return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+
+export function evidenceWindowIssues(
+  provenance: PivotEvidenceProvenance,
+  evidenceCount: number,
+  expectedSessionId: string,
+): string[] {
+  const issues: string[] = [];
+  if (provenance.anchorCoordinate.sessionId !== expectedSessionId) {
+    issues.push("anchor coordinate sessionId does not match candidate sessionId");
+  }
+  if (provenance.anchorCoordinate.role !== "user") {
+    issues.push("anchor coordinate must point to a user turn");
+  }
+
+  const seenEvidence = new Set<number>();
+  let previousEnd = -2;
+  for (const [windowIndex, window] of provenance.evidenceWindows.entries()) {
+    if (window.sessionId !== expectedSessionId) {
+      issues.push(`evidence window ${windowIndex} sessionId does not match candidate sessionId`);
+    }
+    const first = window.turns[0];
+    const last = window.turns[window.turns.length - 1];
+    if (window.startOrdinal !== first.ordinal || window.endOrdinal !== last.ordinal) {
+      issues.push(`evidence window ${windowIndex} bounds do not match its turns`);
+    }
+    if (window.startOrdinal <= previousEnd + 1) {
+      issues.push(`evidence window ${windowIndex} overlaps or should be merged with the previous window`);
+    }
+    previousEnd = window.endOrdinal;
+
+    for (let turnIndex = 0; turnIndex < window.turns.length; turnIndex++) {
+      const turn = window.turns[turnIndex];
+      if (turn.ordinal !== window.startOrdinal + turnIndex) {
+        issues.push(`evidence window ${windowIndex} contains a non-contiguous ordinal range`);
+      }
+      const localIndexes = new Set<number>();
+      for (const evidenceIndex of turn.evidenceIndexes) {
+        if (localIndexes.has(evidenceIndex)) {
+          issues.push(`evidence index ${evidenceIndex} is repeated inside one turn`);
+        }
+        localIndexes.add(evidenceIndex);
+        if (evidenceIndex < 0 || evidenceIndex >= evidenceCount) {
+          issues.push(`evidence index ${evidenceIndex} is outside the candidate evidence array`);
+        } else if (seenEvidence.has(evidenceIndex)) {
+          issues.push(`evidence index ${evidenceIndex} is mapped more than once`);
+        } else {
+          seenEvidence.add(evidenceIndex);
+        }
+      }
+    }
+  }
+  for (let index = 0; index < evidenceCount; index++) {
+    if (!seenEvidence.has(index)) issues.push(`evidence index ${index} has no source coordinate`);
+  }
+  return issues;
+}
+
+/**
+ * Add provenance to content-addressed payloads only when the v1 evidence
+ * contract is present. Historical 2026-08-03 candidates remain byte-for-byte
+ * compatible; a partial or malformed new contract fails closed.
+ */
+export function evidenceIdentityPayload(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const record = value as Record<string, unknown>;
+  if (record.evidenceContractVersion === undefined) return {};
+  return PivotEvidenceProvenanceSchema.parse({
+    evidenceContractVersion: record.evidenceContractVersion,
+    sourceFingerprint: record.sourceFingerprint,
+    anchorCoordinate: record.anchorCoordinate,
+    evidenceWindows: record.evidenceWindows,
+  });
+}

package/src/ppr-traversal.ts

@@ -10,7 +10,11 @@ import type { KGTriple, NeighborhoodResult } from "./kg-store.js";
 // ============================================================================
 
 export interface PPRConfig {
-  /** Teleport probability back to seed nodes (default: 0.85) */
+  /**
+   * Probability of CONTINUING to diffuse along an edge at each step.
+   * The teleport-back-to-seed probability is the complement: (1 - dampingFactor).
+   * (The previous version of this comment had the two reversed.)
+   */
   dampingFactor: number;
   /** Max power-iteration rounds (default: 10) */
   maxIterations: number;
@@ -31,6 +35,26 @@ export interface PPRResult {
   path: string[];
 }
 
+/**
+ * NOTE on dampingFactor = 0.85 (measured 2026-08-28, deliberately NOT changed):
+ *
+ * 0.85 is Brin & Page's default, tuned for billion-node web link graphs.
+ * HippoRAG 2 (arXiv 2502.14802, Table 13) uses 0.5 for knowledge graphs.
+ *
+ * Sensitivity measured on our own production KG (60,536 nodes / 66,332 edges,
+ * 10 real seeds, Top-10 Jaccard against alpha=0.85):
+ *   alpha=0.30 -> 0.617 | 0.50 -> 0.648 | 0.70 -> 0.760 | 0.95 -> 0.598
+ *   alpha=0.30 vs alpha=0.95 -> 0.371  (~63% of results differ)
+ * So the parameter IS sensitive. It is nevertheless left at 0.85, because
+ * tuning it does not fix the actual failure mode: at every alpha tested,
+ * generic hub nodes ("user" / "assistant" / "Alice") take ~30% of the top-20
+ * and land at ranks 2-4. Changing alpha only reshuffles the hubs among
+ * themselves.
+ *
+ * Fix the graph first (entity normalization + hub suppression), then tune.
+ * Revisit only after the top-20 hub share drops materially; any change must
+ * go through a shadow run first.
+ */
 export const DEFAULT_PPR_CONFIG: PPRConfig = {
   dampingFactor: 0.85,
   maxIterations: 10,

package/src/runtime-config.ts

@@ -27,6 +27,11 @@ export interface LocalMemoryConfig {
     dimensions?: number;
     taskQuery?: string;
     taskPassage?: string;
+    /**
+     * Per-request timeout (ms) for the embedding client. Omit to keep the SDK default
+     * (600s in openai v7); `RECALLNEST_EMBEDDING_TIMEOUT_MS` overrides this.
+     */
+    timeoutMs?: number;
   };
   llm?: {
     apiKey: string;
@@ -156,6 +161,10 @@ export function createComponents(config: LocalMemoryConfig, profileName?: string
     dimensions: config.embedding.dimensions,
     taskQuery: config.embedding.taskQuery,
     taskPassage: config.embedding.taskPassage,
+    // Env wins over config.json so a single deployment can bound its embed calls
+    // without editing the shared file. Both unset → no `timeout` reaches the SDK,
+    // which is the behavior every release through v3.0.0 had.
+    timeoutMs: envConfig.embeddingTimeoutMs() ?? config.embedding.timeoutMs,
   };
 
   const embedder = createEmbedder(embeddingConfig);

package/src/session-engine.ts

@@ -8,6 +8,14 @@ import {
 } from "./session-schema.js";
 import { buildIdempotentRecordId } from "./idempotency.js";
 
+/** 当 summary 里每一句都被 repo-state 规则滤掉时的兜底文案（单一来源，勿再字面重复）。 */
+export const FALLBACK_SUMMARY = "Checkpoint captured current task state without repo-state details.";
+
+/** summary 是否已退化成兜底文案——即「本来写了东西，但整段被清洗空了」。 */
+export function isFallbackSummary(summary: string | null | undefined): boolean {
+  return (summary ?? "").trim() === FALLBACK_SUMMARY;
+}
+
 const REPO_STATE_PATTERN = /\bgit status\b|未提交|staged|uncommitted|已修改文件|modified files?|untracked|新增文件|dirty repo|dirty worktree/iu;
 const SENTENCE_SPLIT_PATTERN = /(?:\r?\n)+|(?<=[。！？!?;；])\s+/u;
 const CHECKPOINT_SANITIZABLE_FIELDS = ["summary", "task", "decisions", "openLoops", "nextActions"] as const;
@@ -51,7 +59,7 @@ function sanitizeCheckpointSummary(summary: string): SanitizedStringResult {
     .map(normalizeCheckpointText)
     .filter(Boolean);
   const kept = parts.filter((part) => !hasRepoStateText(part));
-  const value = kept[0] ? kept.join(" ") : "Checkpoint captured current task state without repo-state details.";
+  const value = kept[0] ? kept.join(" ") : FALLBACK_SUMMARY;
   return {
     value,
     changed: kept.length !== parts.length,
@@ -146,13 +154,12 @@ export function buildSessionCheckpointResult(rawInput: unknown): SessionCheckpoi
     resolvedScope: resolveCheckpointScope(sanitizedInput),
   });
 
-  const FALLBACK_SUMMARY = "Checkpoint captured current task state without repo-state details.";
-  const isFallbackSummary = record.summary === FALLBACK_SUMMARY;
+  const summaryIsFallback = isFallbackSummary(record.summary);
   const hasStructuredContent =
     record.decisions.length > 0 ||
     record.openLoops.length > 0 ||
     record.nextActions.length > 0;
-  const quality: CheckpointQuality = isFallbackSummary && !hasStructuredContent ? "minimal" : "rich";
+  const quality: CheckpointQuality = summaryIsFallback && !hasStructuredContent ? "minimal" : "rich";
 
   return {
     record,

package/src/session-output.ts

@@ -1,6 +1,7 @@
 import type { ResumeContextResponse, SessionCheckpointRecord } from "./session-schema.js";
 import { cleanText } from "./context-composer-text.js";
 import { formatIsoAgeLabel } from "./age-label.js";
+import { isFallbackSummary } from "./session-engine.js";
 
 function listBlock(label: string, items: string[]): string[] {
   if (items.length === 0) return [];
@@ -12,7 +13,14 @@ function listBlock(label: string, items: string[]): string[] {
 
 export function formatCheckpointRecallSummary(record: SessionCheckpointRecord): string {
   const parts: string[] = [];
-  const baseSummary = record.summary.trim();
+  const rawSummary = record.summary.trim();
+  // summary 整段被 repo-state 清洗规则滤空时会退化成兜底文案，headline 就只剩一句无信息的
+  // 套话。此时改用第一条实质内容顶上，并保留标记，让读者能分辨「本来就没写」和「被洗掉了」。
+  const substitute = isFallbackSummary(rawSummary)
+    ? [...record.decisions, ...record.nextActions, ...record.openLoops]
+        .find((item) => item.trim().length > 0) ?? ""
+    : "";
+  const baseSummary = substitute ? `[summary sanitized] ${substitute}` : rawSummary;
   if (baseSummary) {
     parts.push(baseSummary);
   }

package/src/session-store.ts

@@ -4,12 +4,11 @@ import { basename, join, resolve } from "node:path";
 import { metaDir } from "./compat.js";
 import type { SessionCheckpointRecord } from "./session-schema.js";
 import { SessionCheckpointRecordSchema } from "./session-schema.js";
-import { normalizeCheckpointScope, type CheckpointQuality } from "./session-engine.js";
+import { isFallbackSummary, normalizeCheckpointScope, type CheckpointQuality } from "./session-engine.js";
 
-const FALLBACK_SUMMARY = "Checkpoint captured current task state without repo-state details.";
 
 export function classifyCheckpointQuality(record: SessionCheckpointRecord): CheckpointQuality {
-  const isFallback = record.summary === FALLBACK_SUMMARY;
+  const isFallback = isFallbackSummary(record.summary);
   const hasContent = record.decisions.length > 0 || record.openLoops.length > 0 || record.nextActions.length > 0;
   return isFallback && !hasContent ? "minimal" : "rich";
 }

package/src/skill-promotion.ts

@@ -34,6 +34,37 @@ export interface PromotionCandidate {
   distinctSources?: number;
 }
 
+/**
+ * 被跨来源判据拒掉的簇 —— 「同一个坑踩了 N 次」。
+ *
+ * 这不是待晋升的规律，是反模式证据：`judgeDistinctSources` 判 `rejected` 时原本只
+ * `rejectedSingleSource++` 然后 continue，信号变成一个数字后消失（同文件下方注释
+ * 早就写着"走 failure-burst 反模式那条路"，而那条路一直不存在）。
+ *
+ * 字段借自 MemTensor/memmy-agent 的 `Memory/src/service/evolution/negative-experience-pipeline.ts`
+ * （其 `NegativeExperienceSource` 枚举里字面就有 `tool_failure_burst`）。
+ * **有意只借它列的证据字段**：memmy 那份 schema 还有 `preference`（该怎么做）与
+ * `verification`（怎么确认没再犯），但那两格要的是判断不是统计 —— 扫描器编出来的
+ * 「该怎么做」比没有更糟。它们列在 `needsJudgement` 里等人或 LLM 填。
+ */
+export interface AntiPatternCandidate {
+  /** 目前只有一条来路；留成联合类型是为了将来接别的信号（如工具连续失败）时不改调用方。 */
+  source: "single_source_burst";
+  /** 撞上它的场景 —— 取簇种子的首行，和 candidates 的 suggestedName 同款提取。 */
+  trigger: string;
+  /** 反模式描述 —— 簇内多条的共性摘要。 */
+  antiPattern: string;
+  /** 同一个坑重复了几次。 */
+  occurrences: number;
+  /** 实际覆盖几个不同来源（判 rejected 说明它 < minDistinctSources）。 */
+  distinctSources: number;
+  /** 0-1。同一来源里重复越多越强，但不因此就变成"规律"。 */
+  evidenceStrength: number;
+  sourceEntries: Array<{ id: string; text: string }>;
+  /** 扫描器有意不填的字段，等判断补上。写死成数组是为了让调用方能机械检查。 */
+  needsJudgement: ReadonlyArray<"preference" | "verification">;
+}
+
 export interface PromotionScanResult {
   candidates: PromotionCandidate[];
   scannedCases: number;
@@ -46,6 +77,12 @@ export interface PromotionScanResult {
   rejectedSingleSource: number;
   /** No-silent-caps 披露:拿不到来源指针、跨来源判据弃权放行的簇数。 */
   abstainedUnknownSource: number;
+  /**
+   * P4 反模式出口:被判 rejected 的簇的**内容**,不只是计数。
+   * 注意与 abstainedUnknownSource 的区别 —— 弃权的簇不进这里:
+   * 不知道来源就不能指控它是「同一个坑踩三次」。
+   */
+  antiPatterns?: AntiPatternCandidate[];
 }
 
 export interface PromotionConfig {
@@ -462,6 +499,7 @@ export async function scanForPromotions(
     vectorlessSkipped: 0,
     rejectedSingleSource: 0,
     abstainedUnknownSource: 0,
+    antiPatterns: [],
   };
 
   // 2. Cluster cases bucket-by-bucket (topicTag, untagged fallback)。
@@ -497,6 +535,19 @@ export async function scanForPromotions(
         const sourceVerdict = judgeDistinctSources(cluster.members, cfg.minDistinctSources);
         if (sourceVerdict.status === "rejected") {
           result.rejectedSingleSource++;
+          // P4:不晋升,但也不让它无声消失 —— 同一个坑重复本身就是要记的东西。
+          // 仍然 continue,晋升判据分毫未动。
+          result.antiPatterns.push({
+            source: "single_source_burst",
+            trigger: extractName(cluster.seed.text),
+            antiPattern: summarizeCluster(cluster.members),
+            occurrences: cluster.members.length,
+            distinctSources: sourceVerdict.distinctSources,
+            // Bayesian smoothing,与 candidates 的 confidence 同款,饱和于 1。
+            evidenceStrength: cluster.members.length / (cluster.members.length + 2),
+            sourceEntries: cluster.members.map(m => ({ id: m.id, text: m.text })),
+            needsJudgement: ["preference", "verification"],
+          });
           continue;
         }
         if (sourceVerdict.status === "abstained") result.abstainedUnknownSource++;
@@ -640,10 +691,25 @@ export function formatPromotionResult(result: PromotionScanResult): string {
   if (result.rejectedSingleSource > 0) {
     lines.push(
       `⚠️ ${result.rejectedSingleSource} cluster(s) had enough entries but too few distinct sources`
-      + ` — 同一次经历的重复不算规律（走 failure-burst 反模式那条路，不是这条）。`,
+      + ` — 同一次经历的重复不算规律（不晋升，改走下面的反模式清单）。`,
     );
   }
 
+  // P4:被拒的簇在这里落地。只显示计数等于让信号消失在一个数字里 ——
+  // 消费者看到的是这段文本,不是 result 对象。
+  // `?.` 不是防御性编程的装饰:PromotionScanResult 是导出接口,旧调用方构造的对象
+  // 没有这个字段,运行时会是 undefined(TS 编译期拦不住外部构造)。
+  if (result.antiPatterns?.length) {
+    lines.push(`\n🔁 ${result.antiPatterns.length} anti-pattern(s) — 同一个坑重复出现，不是规律但要记：\n`);
+    for (const [i, ap] of result.antiPatterns.entries()) {
+      lines.push(`### A${i + 1}. ${ap.trigger}`);
+      lines.push(`重复 ${ap.occurrences} 次，来自 ${ap.distinctSources} 个来源（证据强度 ${(ap.evidenceStrength * 100).toFixed(0)}%）`);
+      lines.push(`共性: ${ap.antiPattern}`);
+      lines.push(`待补判断: ${ap.needsJudgement.join(" / ")} — 扫描器只出证据，「该怎么做」和「怎么确认没再犯」要人或 LLM 填。`);
+      lines.push("");
+    }
+  }
+
   if (result.candidates.length === 0) {
     lines.push("No promotion candidates found.");
     return lines.join("\n");