@stardustlc/dsh-dream 0.5.0 → 0.6.0

package/lib/evidence.d.ts

@@ -0,0 +1,15 @@
+import type { EvidenceInput } from './knowledge.js';
+export interface EvidenceClaim extends EvidenceInput {
+    /** 摘要为转述时，另给原文片段以便核验；不持久化原文。 */
+    quote?: string;
+    artifactPath?: string;
+}
+export interface EvidenceContext {
+    sessionsRoot: string;
+    projectId?: string;
+    workspaceRoot?: string;
+    /** 本地文件只在宿主执行上下文的工作区内读取。 */
+    cwd?: string;
+}
+/** 核验失败保留 claimed 和原因；永远不以模型提供的 hash、verification 或用户角色为准。 */
+export declare function verifyEvidence(claim: EvidenceClaim, context: EvidenceContext): EvidenceInput;

package/lib/evidence.js

@@ -0,0 +1,123 @@
+/** 工具参数只是来源声明；只有本模块读到匹配的可见记录后才产生 read。 */
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, relative, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { decompressAll, listSessionFiles } from './sessions.js';
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function visibleText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.map(visibleText).join('');
+    const item = record(value);
+    if (item.type !== undefined && item.type !== 'text')
+        return '';
+    return visibleText(item.text ?? item.content ?? '');
+}
+function normalized(text) { return text.normalize('NFC').replace(/\s+/g, ' ').trim(); }
+function inside(root, file) {
+    const rel = relative(root, file);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+function samePath(a, b) {
+    const canonical = (p) => { try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    } };
+    const left = canonical(a), right = canonical(b);
+    return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+function readBounded(file, maxBytes) {
+    const stat = statSync(file);
+    if (!stat.isFile() || stat.size > maxBytes)
+        throw new Error('source-unreadable');
+    const bytes = readFileSync(file);
+    if (bytes.length > maxBytes)
+        throw new Error('source-unreadable');
+    return bytes;
+}
+/** 核验失败保留 claimed 和原因；永远不以模型提供的 hash、verification 或用户角色为准。 */
+export function verifyEvidence(claim, context) {
+    const base = {
+        kind: claim.kind, summary: claim.summary, verification: 'claimed',
+        ...(claim.sessionId !== undefined ? { sessionId: claim.sessionId } : {}),
+        ...(claim.recordSeq !== undefined ? { recordSeq: claim.recordSeq } : {}),
+        ...(context.projectId !== undefined ? { projectId: context.projectId } : {}),
+    };
+    const held = (reason) => ({ ...base, verificationReason: reason });
+    if (claim.verification !== 'read')
+        return held('model-claimed');
+    const quote = normalized(claim.quote ?? claim.summary);
+    if (quote === '')
+        return held('quote-missing');
+    try {
+        let text;
+        if (claim.kind === 'local-artifact') {
+            if (!context.cwd || !claim.artifactPath)
+                return held('artifact-context-missing');
+            const root = realpathSync(context.cwd);
+            if (context.workspaceRoot && !samePath(root, context.workspaceRoot))
+                return held('workspace-mismatch');
+            const file = realpathSync(resolve(root, claim.artifactPath));
+            if (!inside(root, file))
+                return held('artifact-outside-workspace');
+            const bytes = readBounded(file, 1024 * 1024);
+            text = bytes.toString('utf8');
+            if (bytes.includes(0) || !Buffer.from(text, 'utf8').equals(bytes))
+                return held('artifact-not-text');
+        }
+        else {
+            if (!claim.sessionId || claim.recordSeq === undefined)
+                return held('session-reference-missing');
+            const root = realpathSync(context.sessionsRoot);
+            const candidates = listSessionFiles(root, 10000).filter(file => basename(dirname(file)) === claim.sessionId);
+            if (candidates.length !== 1)
+                return held('session-not-found-or-ambiguous');
+            const file = realpathSync(candidates[0]);
+            if (!inside(root, file))
+                return held('session-outside-root');
+            if (context.projectId && basename(dirname(dirname(file))) !== context.projectId)
+                return held('project-mismatch');
+            const bytes = readBounded(file, 64 * 1024 * 1024);
+            const content = file.endsWith('.zstd') ? decompressAll(bytes) : bytes.toString('utf8');
+            if (Buffer.byteLength(content) > 64 * 1024 * 1024)
+                return held('source-unreadable');
+            const lines = content.split('\n').filter(line => line.trim() !== '');
+            const header = record(JSON.parse(lines[0] ?? 'null'));
+            if (header.type !== 'session' || header.id !== claim.sessionId || (header.version !== undefined && ![0, 1, 2, 3, 4].includes(header.version)))
+                return held('session-header-mismatch');
+            if (context.workspaceRoot && (typeof header.cwd !== 'string' || !samePath(header.cwd, context.workspaceRoot)))
+                return held('workspace-mismatch');
+            const found = [];
+            for (const line of lines.slice(1)) {
+                try {
+                    const item = record(JSON.parse(line));
+                    if (item.seq !== undefined && String(item.seq) === String(claim.recordSeq))
+                        found.push(item);
+                }
+                catch { /* 坏行不是证据 */ }
+            }
+            if (found.length !== 1)
+                return held('record-not-found-or-ambiguous');
+            const entry = found[0], data = record(entry.data);
+            if (claim.kind === 'user-correction' && (entry.type !== 'user/message' || (header.version >= 4 && record(data.source).kind !== 'user')))
+                return held('not-human-message');
+            if (entry.type !== 'user/message' && entry.type !== 'assistant/message' && entry.type !== 'tool/result')
+                return held('record-not-visible');
+            text = visibleText(data.content ?? data.text ?? data.message ?? entry.data);
+        }
+        if (!normalized(text).includes(quote))
+            return held('quote-mismatch');
+        const hash = createHash('sha256').update(text, 'utf8').digest('hex');
+        if (claim.sourceHash !== undefined && claim.sourceHash !== hash)
+            return held('source-hash-mismatch');
+        return { ...base, verification: 'read', sourceHash: hash, verificationReason: 'source-verified' };
+    }
+    catch {
+        return held('source-unreadable');
+    }
+}

package/lib/journal.d.ts

@@ -9,6 +9,19 @@ export interface DreamEntry {
 export declare function journalFile(journalDir: string): string;
 /** 追加一条梦；返回落盘后的条目。 */
 export declare function saveDream(journalDir: string, reflection: string, lessons: string[], mood: string): DreamEntry;
+/** 读取结果：梦境 + 被跳过的行数（坏 JSON 或不是梦境记录）。 */
+export interface DreamReadResult {
+    dreams: DreamEntry[];
+    skippedLines: number;
+}
+/**
+ * 倒序读取梦境并**报告**跳过了多少行。
+ *
+ * 两个健壮性要求（评审实测发现）：
+ * - 文件开头的 UTF-8 BOM 必须剥离，否则第一行解析失败会让整份日记读空；
+ * - 坏行跳过要可计数，不能静默——调用方（dream_health / 只读路由）可以透出。
+ */
+export declare function readDreamsDetailed(journalDir: string, limit: number): DreamReadResult;
 /** 倒序读取梦境（新梦在前）；损坏行跳过。 */
 export declare function readDreams(journalDir: string, limit: number): DreamEntry[];
 /** 教训榜的一行：次数与最近一次出现时间（lastAt 缺失时是空串，绝不为 null）。 */
@@ -22,6 +35,8 @@ export interface DreamStats {
     total: number;
     moods: Record<string, number>;
     topLessons: LessonStat[];
+    /** 解析时跳过的行数（坏 JSON 或不是梦境记录）；0 表示全部可读。 */
+    skippedLines: number;
 }
 /**
  * 统计梦境（基于全量日记）。

package/lib/journal.js

@@ -26,18 +26,27 @@ export function saveDream(journalDir, reflection, lessons, mood) {
 }
 /** 需要读全量日记时的上限：检索与统计共用，避免两处上限漂移。 */
 const FULL_SCAN_LIMIT = 100000;
-/** 倒序读取梦境（新梦在前）；损坏行跳过。 */
-export function readDreams(journalDir, limit) {
+/**
+ * 倒序读取梦境并**报告**跳过了多少行。
+ *
+ * 两个健壮性要求（评审实测发现）：
+ * - 文件开头的 UTF-8 BOM 必须剥离，否则第一行解析失败会让整份日记读空；
+ * - 坏行跳过要可计数，不能静默——调用方（dream_health / 只读路由）可以透出。
+ */
+export function readDreamsDetailed(journalDir, limit) {
     const file = journalFile(journalDir);
     if (!existsSync(file))
-        return [];
-    const lines = readFileSync(file, 'utf8').split('\n').filter((line) => line.trim() !== '');
-    const out = [];
+        return { dreams: [], skippedLines: 0 };
+    // 开头 BOM 不参与解析（Windows 记事本等工具会写入）。
+    const text = readFileSync(file, 'utf8').replace(/^\uFEFF/, '');
+    const lines = text.split('\n').filter((line) => line.trim() !== '');
+    const dreams = [];
+    let skippedLines = 0;
     for (const line of lines) {
         try {
             const rec = JSON.parse(line);
             if (typeof rec.reflection === 'string') {
-                out.push({
+                dreams.push({
                     id: String(rec.id ?? ''),
                     at: String(rec.at ?? ''),
                     reflection: rec.reflection,
@@ -45,10 +54,18 @@ export function readDreams(journalDir, limit) {
                     mood: typeof rec.mood === 'string' ? rec.mood : '',
                 });
             }
+            else
+                skippedLines += 1;
+        }
+        catch {
+            skippedLines += 1;
         }
-        catch { /* 损坏行跳过 */ }
     }
-    return out.reverse().slice(0, limit);
+    return { dreams: dreams.reverse().slice(0, limit), skippedLines };
+}
+/** 倒序读取梦境（新梦在前）；损坏行跳过。 */
+export function readDreams(journalDir, limit) {
+    return readDreamsDetailed(journalDir, limit).dreams;
 }
 /**
  * 统计梦境（基于全量日记）。
@@ -58,8 +75,10 @@ export function readDreams(journalDir, limit) {
  * 大小写，不再二次 flatMap（否则同一条教训的三个数值会来自不同的扫描）。
  */
 export function dreamStats(journalDir) {
-    const dreams = readDreams(journalDir, FULL_SCAN_LIMIT);
-    const moods = {};
+    const { dreams, skippedLines } = readDreamsDetailed(journalDir, FULL_SCAN_LIMIT);
+    // 无原型对象：心境是用户可控文本，'__proto__' / 'constructor' 这类键
+    // 在普通对象上会被原型吞掉或把计数变成字符串（评审实测）。
+    const moods = Object.create(null);
     const lessons = new Map();
     for (const dream of dreams) {
         const mood = dream.mood !== '' ? dream.mood : '平静';
@@ -78,7 +97,9 @@ export function dreamStats(journalDir) {
     const topLessons = [...lessons.values()]
         .sort((a, b) => b.count - a.count || b.lastAt.localeCompare(a.lastAt))
         .slice(0, 10);
-    return { total: dreams.length, moods, topLessons };
+    // 对外给普通对象副本：内部用无原型对象防键污染，但消费方（deepStrictEqual / 原型判断）
+    // 期望的是普通对象。展开赋值走 CreateDataProperty，不会触发 __proto__ setter。
+    return { total: dreams.length, moods: { ...moods }, topLessons, skippedLines };
 }
 /** 关键词检索梦境（不区分大小写，命中 reflection/lessons；扫描全量，上限见 FULL_SCAN_LIMIT）。 */
 export function searchDreams(journalDir, query, limit) {

package/lib/knowledge-store.d.ts

@@ -1,4 +1,4 @@
-import { type Evidence, type EvidenceInput, type Lesson, type LessonInput, type LessonState, type ReviewDecision } from './knowledge.js';
+import { type Evidence, type EvidenceInput, type Lesson, type LessonInput, type LessonReviewResolution, type LessonState, type ReviewDecision } from './knowledge.js';
 /** events.jsonl 默认最多回放的行数（有界读取）。 */
 export declare const MAX_REPLAY_EVENTS = 200000;
 /** KnowledgeStore 构造选项（都可省略，保持 FREEZE 的 constructor(knowledgeDir) 可用）。 */
@@ -11,6 +11,10 @@ export interface KnowledgeStoreOptions {
     lockTimeoutMs?: number;
     /** 锁年龄超过该毫秒数且 pid 不存活才允许接管；默认 30000。 */
     lockStaleMs?: number;
+    /** 锁硬上限：超过且心跳停滞时给可操作错误、不静默抢占；默认 600000（10 分钟）。 */
+    lockHardLimitMs?: number;
+    /** 心跳刷新间隔毫秒；默认 5000。长回放/压缩也会按行数主动 touch。 */
+    lockHeartbeatMs?: number;
 }
 /**
  * 经验知识存储。无文件时所有读取方法安全返回空，写入方法在首次写入时自建目录。
@@ -25,6 +29,9 @@ export declare class KnowledgeStore {
     private readonly maxReplayEvents;
     private readonly lockTimeoutMs;
     private readonly lockStaleMs;
+    private readonly lockHardLimitMs;
+    private readonly lockHeartbeatMs;
+    private lastIndexError?;
     constructor(knowledgeDir: string, options?: KnowledgeStoreOptions);
     /** 全部经验，按 updatedAt 降序（同刻按 id 稳定排序）。 */
     listLessons(): Lesson[];
@@ -38,22 +45,36 @@ export declare class KnowledgeStore {
         created: boolean;
     };
     /**
-     * 创建候选经验。同 idempotencyKey 幂等；同指纹（文本 + 范围相同）确定性合并，
+     * 创建候选经验。同 idempotencyKey + 同 requestHash 幂等；同指纹（文本 + 范围相同）确定性合并，
      * 只把新证据并入已有经验，不新增经验。
+     * 经调用方核验的 read 来源可用于项目经验；来源读取不代表用户采纳，review 始终 unreviewed。
      */
-    createLesson(input: LessonInput, idempotencyKey: string): {
+    createLesson(input: LessonInput, idempotencyKey: string, options?: {
+        requireReview?: boolean;
+    }): {
         lesson: Lesson;
         created: boolean;
     };
-    /** 按 patch 更新经验；revision 不符抛 KnowledgeError('revision') 且不写。 */
+    /** 追加证据与更新引用共用一把锁；先检查 revision 与全部输入，不改变审阅状态。 */
+    attachEvidence(id: string, inputs: EvidenceInput[], expectedRevision: number, idempotencyKey: string): Lesson;
+    /** 按 patch 更新经验；revision 不符抛 KnowledgeError('revision')（details 带 currentRevision）且不写。 */
     updateLesson(id: string, patch: Partial<Lesson>, expectedRevision: number, idempotencyKey: string): Lesson;
     /** 审阅经验：accepted → usable，rejected → rejected，unreviewed → candidate。 */
-    reviewLesson(id: string, decision: ReviewDecision, expectedRevision: number, idempotencyKey: string, actor?: string): Lesson;
+    reviewLesson(id: string, decision: ReviewDecision, expectedRevision: number, idempotencyKey: string, actor?: string, note?: string, resolution?: LessonReviewResolution): Lesson;
+    /**
+     * 批量原子更新（M2-②）：一个事件承载全部变更；先统一校验，
+     * 任一条不通过 → 零写入并抛 KnowledgeError（details.failedId）。
+     */
+    updateLessonsBatch(updates: Array<{
+        id: string;
+        patch: Partial<Lesson>;
+        expectedRevision: number;
+    }>, idempotencyKey: string): Lesson[];
     /** 状态迁移；不允许的迁移抛 KnowledgeError('invalid') 且不写。 */
     applyTransition(id: string, to: LessonState, expectedRevision: number, idempotencyKey: string): Lesson;
-    /** 从事件重建派生索引；不删除、不改写 events.jsonl / evidence.jsonl。 */
+    /** 从事件完整重建派生索引与 checkpoint；不删除、不改写 events.jsonl / evidence.jsonl。 */
     rebuildIndex(): void;
-    /** 统计。truncated=true 表示回放被 MAX_REPLAY_EVENTS 截断（不静默）。 */
+    /** 统计。truncated=true 表示事件总量超过有界回放上限（不静默）；快照模式下实体已折叠进 checkpoint。 */
     stats(): {
         lessons: number;
         evidence: number;
@@ -61,15 +82,91 @@ export declare class KnowledgeStore {
         byState: Record<LessonState, number>;
         truncated: boolean;
         badLines: number;
+        orphanEvents: number;
+        unsupportedVersions: number;
+        skippedEvents: number;
+        firstReplayedEventId?: string;
+        replayMode: 'full' | 'snapshot+tail';
+        replayedEvents: number;
+        unreplayedEvents: number;
+    };
+    /** 只读诊断：锁、文件、计数与最近一次派生索引写失败；绝不获取锁、绝不写盘。 */
+    diagnose(): {
+        writable: boolean;
+        lock: {
+            present: boolean;
+            ageMs?: number;
+            pid?: number;
+            alive?: boolean;
+            bootId?: string;
+            stale: boolean;
+        };
+        files: {
+            dir: string;
+            events: {
+                path: string;
+                exists: boolean;
+                bytes: number;
+            };
+            evidence: {
+                path: string;
+                exists: boolean;
+                bytes: number;
+            };
+            index: {
+                path: string;
+                exists: boolean;
+                bytes: number;
+                generatedAt?: string;
+            };
+        };
+        counts: {
+            lessons: number;
+            evidence: number;
+            events: number;
+            badLines: number;
+            orphanEvents: number;
+            unsupportedVersions: number;
+            skippedEvents: number;
+            truncated: boolean;
+            byState: Record<LessonState, number>;
+        };
+        lastIndexError?: {
+            message: string;
+            at: string;
+        };
     };
     private ensureDir;
     private withLock;
-    /** 有界读取 JSONL：只保留最后 maxReplayEvents 条非空行，并报告总行数与截断。 */
+    private fileInfo;
+    private hashRequest;
+    private hashablePatch;
+    private cleanPatch;
+    private assertSameRequest;
+    /**
+     * 恢复"首次结果"：
+     * - 尾部回放产生的 entry 自带快照，直接返回；
+     * - checkpoint 里的 entry 只有 lessonId/requestHash，则做一次有针对性的完整扫描，
+     *   在命中该幂等键的那一刻取快照；失败再退回当前实体（best effort）。
+     */
+    private resolveIdempotentLesson;
+    private resolveIdempotentBatch;
+    private replayUntilIdempotencyKey;
+    /** 顺序读取 JSONL 的非空行；每 TOUCH_EVERY_LINES 行调用一次 touch（长回放锁心跳）。 */
+    private forEachLine;
+    /** 有界读取：只保留最后 maxReplayEvents 条非空行，并报告总行数与是否截断。 */
     private readBoundedLines;
-    /** 只回放事件流。 */
+    /** 快照 + 尾部增量（checkpoint 有效时）；否则有界全量回放。 */
     private loadEvents;
+    private loadEventsBounded;
+    /** 无界完整回放（显式压缩 / 写路径发现截断或状态不完整时使用）。 */
+    private loadAllUnbounded;
     /** 事件流 + evidence.jsonl（两条路径都留痕，按 id 合并去重）。 */
     private loadAll;
+    /** 写路径：状态不完整、证据疑似缺失或截断未折叠时，自动做一次完整回放。 */
+    private loadCompleteState;
+    private hasMissingEvidenceRefs;
+    private mergeEvidenceFile;
     private applyEventLine;
     private appendEvent;
     private appendLine;
@@ -80,8 +177,12 @@ export declare class KnowledgeStore {
     private appendLessonUpdate;
     private maskLesson;
     private maskEvidence;
+    private hashPrefix;
+    private readLastLineId;
+    private tryLoadCheckpoint;
+    private buildCheckpoint;
     private buildIndexPayload;
-    /** 自动更新派生索引：失败降级（权威事件已落盘），不推翻调用结果。 */
+    /** 自动更新派生索引：失败降级（权威事件已落盘），记录 lastIndexError 供 diagnose()。 */
     private writeIndex;
     private writeIndexStrict;
 }