@stardustlc/dsh-dream 0.5.1 → 0.7.0

package/lib/knowledge-store.js

@@ -214,6 +214,7 @@ function acquireLock(lockPath, options) {
         sleepSync(25);
     }
 }
+const KNOWN_EVENT_KINDS = new Set(['lesson.create', 'lesson.update', 'lesson.review', 'lesson.batch', 'evidence.add']);
 /** 事件行形状检查（字段值再做 schema 校验）。 */
 function isEventShape(value) {
     if (!isRecord(value) || value.schemaVersion !== 1)
@@ -234,6 +235,16 @@ function isEventShape(value) {
                 typeof value.revision === 'number' &&
                 Number.isInteger(value.revision) &&
                 value.payload !== undefined);
+        case 'lesson.batch': {
+            if (!isRecord(value.payload) || !Array.isArray(value.payload.updates))
+                return false;
+            return value.payload.updates.every((item) => isRecord(item) &&
+                typeof item.lessonId === 'string' &&
+                item.lessonId !== '' &&
+                typeof item.revision === 'number' &&
+                Number.isInteger(item.revision) &&
+                isRecord(item.patch));
+        }
         case 'evidence.add':
             return value.payload !== undefined;
         default:
@@ -268,6 +279,7 @@ function createEmptyReplayState() {
         badLines: 0,
         orphanEvents: 0,
         unsupportedVersions: 0,
+        skippedEvents: 0,
         replayMode: 'full',
         idempotencyComplete: true,
         entitiesFromSnapshot: false,
@@ -346,9 +358,9 @@ export class KnowledgeStore {
     /**
      * 创建候选经验。同 idempotencyKey + 同 requestHash 幂等；同指纹（文本 + 范围相同）确定性合并，
      * 只把新证据并入已有经验，不新增经验。
-     * R2′：有 read 证据 → 初始 usable（含 user-correction read 时 review=accepted/user）；只有 claimed 或无证据 → candidate。
+     * 经调用方核验的 read 来源可用于项目经验；来源读取不代表用户采纳，review 始终 unreviewed。
      */
-    createLesson(input, idempotencyKey) {
+    createLesson(input, idempotencyKey, options = {}) {
         assertIdempotencyKey(idempotencyKey);
         if (!isRecord(input))
             throw new KnowledgeError('invalid', '经验输入必须是对象');
@@ -358,6 +370,7 @@ export class KnowledgeStore {
         const evidenceInputs = input.evidence === undefined ? [] : input.evidence;
         const requestHash = this.hashRequest({
             operation: 'lesson.create',
+            ...(options.requireReview === true ? { requireReview: true } : {}),
             kind: input.kind === undefined ? null : input.kind,
             title: input.title === undefined ? null : input.title,
             action: input.action === undefined ? null : input.action,
@@ -424,27 +437,20 @@ export class KnowledgeStore {
                     .map((id) => state.evidence.get(id))
                     .filter((item) => item !== undefined);
                 const hasRead = mergedEvidence.some((item) => item.verification === 'read');
-                const hasUserCorrectionRead = mergedEvidence.some((item) => item.kind === 'user-correction' && item.verification === 'read');
                 const patch = {};
                 if (newIds.length > 0) {
                     patch.evidenceIds = mergedIds;
-                    patch.independentSupportCount = mergeEvidenceSupport({ evidenceIds: mergedIds }, Array.from(state.evidence.values()));
                 }
+                const supportCount = mergeEvidenceSupport({ evidenceIds: mergedIds }, Array.from(state.evidence.values()));
+                if (supportCount !== existing.independentSupportCount)
+                    patch.independentSupportCount = supportCount;
                 // R2′：候选经验遇到 read 证据可升为 usable；disputed/stale/rejected 状态保持不变。
-                if (existing.state === 'candidate' && hasRead) {
+                if (existing.state === 'candidate' && hasRead && !options.requireReview) {
                     patch.state = 'usable';
-                    if (hasUserCorrectionRead) {
-                        patch.review = { decision: 'accepted', actor: 'user', at: now };
-                    }
-                    else if (existing.review.decision !== 'unreviewed') {
+                    if (existing.review.decision !== 'unreviewed') {
                         patch.review = { decision: 'unreviewed' };
                     }
                 }
-                else if (existing.state === 'usable' &&
-                    hasUserCorrectionRead &&
-                    existing.review.decision !== 'accepted') {
-                    patch.review = { decision: 'accepted', actor: 'user', at: now };
-                }
                 if (Object.keys(patch).length === 0)
                     return { lesson: clone(existing), created: false };
                 const merged = this.appendLessonUpdate(state, existing, patch, idempotencyKey, requestHash, touch);
@@ -455,11 +461,8 @@ export class KnowledgeStore {
                 .map((id) => state.evidence.get(id))
                 .filter((item) => item !== undefined);
             const hasRead = allEvidence.some((item) => item.verification === 'read');
-            const hasUserCorrectionRead = allEvidence.some((item) => item.kind === 'user-correction' && item.verification === 'read');
-            const initialState = hasRead ? 'usable' : 'candidate';
-            const initialReview = hasUserCorrectionRead
-                ? { decision: 'accepted', actor: 'user', at: now }
-                : { decision: 'unreviewed' };
+            const initialState = hasRead && !options.requireReview ? 'usable' : 'candidate';
+            const initialReview = { decision: 'unreviewed' };
             const lesson = validateLesson({
                 schemaVersion: 1,
                 id: 'lsn_' + randomUUID(),
@@ -499,6 +502,41 @@ export class KnowledgeStore {
             return { lesson: clone(stored), created: true };
         });
     }
+    /** 追加证据与更新引用共用一把锁；先检查 revision 与全部输入，不改变审阅状态。 */
+    attachEvidence(id, inputs, expectedRevision, idempotencyKey) {
+        assertIdempotencyKey(idempotencyKey);
+        if (!Array.isArray(inputs) || inputs.length === 0)
+            throw new KnowledgeError('invalid', 'attach-evidence 需要非空 evidence 数组');
+        const requestHash = this.hashRequest({ operation: 'lesson.attach-evidence', id, inputs });
+        return this.withLock((touch) => {
+            const state = this.loadCompleteState(touch);
+            const cached = state.idempotency.get(idempotencyKey);
+            if (cached) {
+                this.assertSameRequest(cached, requestHash, idempotencyKey);
+                const lesson = this.resolveIdempotentLesson(state, idempotencyKey);
+                if (!lesson)
+                    throw new KnowledgeError('io', '无法恢复追加证据结果');
+                return lesson;
+            }
+            const previous = state.lessons.get(id);
+            if (!previous)
+                throw new KnowledgeError('invalid', '经验不存在：' + id);
+            if (previous.revision !== expectedRevision)
+                throw new KnowledgeError('revision', '经验 revision 已变化', { currentRevision: previous.revision });
+            for (const item of inputs)
+                validateEvidence({ ...item, id: 'evd_probe', schemaVersion: 1, observedAt: item.observedAt ?? new Date().toISOString() });
+            const ids = [...previous.evidenceIds];
+            for (const item of inputs) {
+                const evidence = this.persistEvidenceLocked(item, state);
+                if (!ids.includes(evidence.id))
+                    ids.push(evidence.id);
+            }
+            const count = mergeEvidenceSupport({ evidenceIds: ids }, [...state.evidence.values()]);
+            if (ids.length === previous.evidenceIds.length && count === previous.independentSupportCount)
+                return clone(previous);
+            return clone(this.appendLessonUpdate(state, previous, { evidenceIds: ids, independentSupportCount: count }, idempotencyKey, requestHash, touch));
+        });
+    }
     /** 按 patch 更新经验；revision 不符抛 KnowledgeError('revision')（details 带 currentRevision）且不写。 */
     updateLesson(id, patch, expectedRevision, idempotencyKey) {
         assertIdempotencyKey(idempotencyKey);
@@ -535,13 +573,56 @@ export class KnowledgeStore {
             return clone(this.appendLessonUpdate(state, lesson, clean, idempotencyKey, requestHash, touch));
         });
     }
+    /** 记录一次使用反馈，不改变审阅、状态、证据和最后核验时间。 */
+    recordFeedback(id, vote, note, expectedRevision, idempotencyKey) {
+        assertIdempotencyKey(idempotencyKey);
+        if (vote !== 'useful' && vote !== 'not-applicable')
+            throw new KnowledgeError('invalid', '反馈必须是 useful / not-applicable');
+        if (!Number.isInteger(expectedRevision) || expectedRevision < 1)
+            throw new KnowledgeError('invalid', '反馈必须带有效的经验版本');
+        if (note !== undefined && (typeof note !== 'string' || note.length > 500))
+            throw new KnowledgeError('invalid', '反馈备注最多 500 字符');
+        const cleanNote = note === undefined || note.trim() === '' ? undefined : this.mask ? maskSecrets(note.trim()) : note.trim();
+        const requestHash = this.hashRequest({ operation: 'lesson.feedback', id, vote, note: cleanNote ?? null, expectedRevision });
+        return this.withLock((touch) => {
+            const state = this.loadCompleteState(touch);
+            const cached = state.idempotency.get(idempotencyKey);
+            if (cached !== undefined) {
+                this.assertSameRequest(cached, requestHash, idempotencyKey);
+                const result = this.resolveIdempotentLesson(state, idempotencyKey);
+                if (result === undefined)
+                    throw new KnowledgeError('io', '无法恢复反馈结果');
+                return result;
+            }
+            const previous = state.lessons.get(id);
+            if (previous === undefined)
+                throw new KnowledgeError('invalid', '经验不存在：' + id);
+            if (previous.revision !== expectedRevision)
+                throw new KnowledgeError('revision', '经验已更新，请刷新后再反馈', { currentRevision: previous.revision });
+            const old = previous.feedback ?? { useful: 0, notApplicable: 0, recent: [] };
+            const feedback = {
+                useful: old.useful + (vote === 'useful' ? 1 : 0),
+                notApplicable: old.notApplicable + (vote === 'not-applicable' ? 1 : 0),
+                recent: [...old.recent, { vote, at: new Date().toISOString(), ...(cleanNote === undefined ? {} : { note: cleanNote }) }].slice(-20),
+            };
+            return clone(this.appendLessonUpdate(state, previous, { feedback }, idempotencyKey, requestHash, touch));
+        });
+    }
     /** 审阅经验：accepted → usable，rejected → rejected，unreviewed → candidate。 */
-    reviewLesson(id, decision, expectedRevision, idempotencyKey, actor) {
+    reviewLesson(id, decision, expectedRevision, idempotencyKey, actor, note, resolution) {
         assertIdempotencyKey(idempotencyKey);
         if (!isEnum(decision, REVIEW_DECISIONS))
             throw new KnowledgeError('invalid', 'review decision 取值不合法');
         const maskedActor = actor === undefined ? undefined : this.mask ? maskSecrets(actor) : actor;
-        const requestHash = this.hashRequest({ operation: 'lesson.review', lessonId: id, decision, actor: maskedActor === undefined ? null : maskedActor });
+        const maskedNote = note === undefined ? undefined : this.mask ? maskSecrets(note) : note;
+        const requestHash = this.hashRequest({
+            operation: 'lesson.review',
+            lessonId: id,
+            decision,
+            actor: maskedActor === undefined ? null : maskedActor,
+            note: maskedNote === undefined ? null : maskedNote,
+            resolution: resolution === undefined ? null : resolution,
+        });
         return this.withLock((touch) => {
             const state = this.loadCompleteState(touch);
             const cached = state.idempotency.get(idempotencyKey);
@@ -567,18 +648,27 @@ export class KnowledgeStore {
                 throw new KnowledgeError('invalid', '不允许的审阅迁移：' + lesson.state + ' → ' + nextState, { lessonId: id });
             }
             const now = new Date().toISOString();
+            const nextReview = { decision, at: now };
+            if (maskedActor !== undefined)
+                nextReview.actor = maskedActor;
+            if (maskedNote !== undefined)
+                nextReview.note = maskedNote;
+            if (resolution !== undefined)
+                nextReview.resolution = resolution;
             const merged = validateLesson({
                 ...lesson,
                 state: nextState,
-                review: maskedActor === undefined
-                    ? { decision, at: now }
-                    : { decision, actor: maskedActor, at: now },
+                review: nextReview,
                 revision: lesson.revision + 1,
                 updatedAt: now,
             });
             const payload = { decision, state: nextState };
             if (maskedActor !== undefined)
                 payload.actor = maskedActor;
+            if (maskedNote !== undefined)
+                payload.note = maskedNote;
+            if (resolution !== undefined)
+                payload.resolution = resolution;
             const event = {
                 schemaVersion: 1,
                 id: 'evt_' + randomUUID(),
@@ -599,6 +689,97 @@ export class KnowledgeStore {
             return clone(merged);
         });
     }
+    /**
+     * 批量原子更新（M2-②）：一个事件承载全部变更；先统一校验，
+     * 任一条不通过 → 零写入并抛 KnowledgeError（details.failedId）。
+     */
+    updateLessonsBatch(updates, idempotencyKey) {
+        assertIdempotencyKey(idempotencyKey);
+        if (!Array.isArray(updates) || updates.length === 0)
+            throw new KnowledgeError('invalid', 'updates 必须是非空数组');
+        for (const update of updates) {
+            if (!isRecord(update) || typeof update.id !== 'string' || update.id.trim() === '' || !isRecord(update.patch)) {
+                throw new KnowledgeError('invalid', 'updates 每项必须包含 id/patch/expectedRevision');
+            }
+            if (typeof update.expectedRevision !== 'number' || !Number.isInteger(update.expectedRevision)) {
+                throw new KnowledgeError('invalid', 'expectedRevision 必须是整数', { failedId: update.id });
+            }
+        }
+        const requestHash = this.hashRequest({
+            operation: 'lesson.batch',
+            updates: updates.map((update) => ({ id: update.id, expectedRevision: update.expectedRevision, patch: this.hashablePatch(update.patch) })),
+        });
+        return this.withLock((touch) => {
+            const state = this.loadCompleteState(touch);
+            const cached = state.idempotency.get(idempotencyKey);
+            if (cached !== undefined) {
+                this.assertSameRequest(cached, requestHash, idempotencyKey);
+                const batch = this.resolveIdempotentBatch(state, idempotencyKey);
+                if (batch === undefined)
+                    throw new KnowledgeError('io', '无法恢复批量幂等键的历史结果：' + idempotencyKey, { idempotencyKey });
+                return batch;
+            }
+            const now = new Date().toISOString();
+            const planned = [];
+            for (const update of updates) {
+                const previous = state.lessons.get(update.id);
+                if (previous === undefined)
+                    throw new KnowledgeError('invalid', '经验不存在：' + update.id, { failedId: update.id });
+                if (previous.revision !== update.expectedRevision) {
+                    throw new KnowledgeError('revision', '经验 ' + update.id + ' 期望 revision ' + update.expectedRevision + '，实际 ' + previous.revision, {
+                        failedId: update.id,
+                        expectedRevision: update.expectedRevision,
+                        currentRevision: previous.revision,
+                    });
+                }
+                const clean = this.cleanPatch(update.patch);
+                if (clean.state !== undefined && clean.state !== previous.state && !canTransition(previous.state, clean.state)) {
+                    throw new KnowledgeError('invalid', '不允许的状态迁移：' + previous.state + ' → ' + clean.state, { failedId: update.id });
+                }
+                if (clean.evidenceIds !== undefined) {
+                    clean.independentSupportCount = mergeEvidenceSupport({ evidenceIds: clean.evidenceIds }, Array.from(state.evidence.values()));
+                }
+                const merged = this.maskLesson(validateLesson({
+                    ...previous,
+                    ...clean,
+                    id: previous.id,
+                    schemaVersion: 1,
+                    revision: previous.revision + 1,
+                    updatedAt: now,
+                }));
+                planned.push({ previous, merged, patch: clean });
+            }
+            const event = {
+                schemaVersion: 1,
+                id: 'evt_' + randomUUID(),
+                at: now,
+                kind: 'lesson.batch',
+                idempotencyKey,
+                requestHash,
+                payload: {
+                    updates: planned.map(({ previous, merged, patch: clean }) => {
+                        const patch = {};
+                        for (const key of Object.keys(clean)) {
+                            ;
+                            patch[key] = merged[key];
+                        }
+                        return { lessonId: previous.id, revision: merged.revision, patch };
+                    }),
+                },
+            };
+            this.appendEvent(state, event);
+            const applied = [];
+            for (const { merged } of planned) {
+                state.lessons.set(merged.id, merged);
+                applied.push(merged);
+            }
+            if (!state.idempotency.has(idempotencyKey)) {
+                state.idempotency.set(idempotencyKey, { lessonId: applied[0].id, requestHash, batch: applied, lessonIds: applied.map((lesson) => lesson.id) });
+            }
+            this.writeIndex(state, touch);
+            return clone(applied);
+        });
+    }
     /** 状态迁移；不允许的迁移抛 KnowledgeError('invalid') 且不写。 */
     applyTransition(id, to, expectedRevision, idempotencyKey) {
         assertIdempotencyKey(idempotencyKey);
@@ -653,10 +834,11 @@ export class KnowledgeStore {
             badLines: state.badLines,
             orphanEvents: state.orphanEvents,
             unsupportedVersions: state.unsupportedVersions,
+            skippedEvents: state.skippedEvents,
             firstReplayedEventId: state.firstReplayedEventId,
             replayMode: state.replayMode,
             replayedEvents: state.replayedEvents,
-            skippedEvents: Math.max(0, state.events - state.replayedEvents),
+            unreplayedEvents: Math.max(0, state.events - state.replayedEvents),
         };
     }
     /** 只读诊断：锁、文件、计数与最近一次派生索引写失败；绝不获取锁、绝不写盘。 */
@@ -703,6 +885,7 @@ export class KnowledgeStore {
                 badLines: state.badLines,
                 orphanEvents: state.orphanEvents,
                 unsupportedVersions: state.unsupportedVersions,
+                skippedEvents: state.skippedEvents,
                 truncated: state.events > this.maxReplayEvents,
                 byState,
             },
@@ -789,11 +972,29 @@ export class KnowledgeStore {
         if (entry.lesson !== undefined)
             return clone(entry.lesson);
         const exact = this.replayUntilIdempotencyKey(idempotencyKey);
-        if (exact !== undefined)
-            return clone(exact);
+        if (exact !== undefined && exact.lesson !== undefined)
+            return clone(exact.lesson);
         const current = state.lessons.get(entry.lessonId);
         return current === undefined ? undefined : clone(current);
     }
+    resolveIdempotentBatch(state, idempotencyKey) {
+        const entry = state.idempotency.get(idempotencyKey);
+        if (entry === undefined)
+            return undefined;
+        if (entry.batch !== undefined)
+            return clone(entry.batch);
+        const exact = this.replayUntilIdempotencyKey(idempotencyKey);
+        if (exact !== undefined && exact.batch !== undefined)
+            return clone(exact.batch);
+        const ids = entry.lessonIds !== undefined ? entry.lessonIds : [entry.lessonId];
+        const out = [];
+        for (const id of ids) {
+            const lesson = state.lessons.get(id);
+            if (lesson !== undefined)
+                out.push(clone(lesson));
+        }
+        return out.length === 0 ? undefined : out;
+    }
     replayUntilIdempotencyKey(idempotencyKey) {
         const state = createEmptyReplayState();
         let found;
@@ -802,8 +1003,8 @@ export class KnowledgeStore {
                 state.events++;
                 this.applyEventLine(state, line);
                 const hit = state.idempotency.get(idempotencyKey);
-                if (hit !== undefined && hit.lesson !== undefined) {
-                    found = hit.lesson;
+                if (hit !== undefined && (hit.lesson !== undefined || hit.batch !== undefined)) {
+                    found = hit;
                     return false;
                 }
                 return true;
@@ -887,6 +1088,7 @@ export class KnowledgeStore {
             state.badLines = snapshot.checkpoint.counters.badLines;
             state.orphanEvents = snapshot.checkpoint.counters.orphanEvents;
             state.unsupportedVersions = snapshot.checkpoint.counters.unsupportedVersions;
+            state.skippedEvents = snapshot.checkpoint.counters.skippedEvents;
             state.snapshotEvidenceCount = snapshot.checkpoint.counters.evidenceCount;
             state.idempotencyComplete = snapshot.checkpoint.idempotencyComplete === true;
             state.lastEventId = snapshot.checkpoint.lastEventId;
@@ -995,6 +1197,11 @@ export class KnowledgeStore {
             state.unsupportedVersions++;
             return;
         }
+        const kind = raw.kind;
+        if (typeof kind !== 'string' || !KNOWN_EVENT_KINDS.has(kind)) {
+            state.skippedEvents++;
+            return;
+        }
         if (!isEventShape(raw)) {
             state.badLines++;
             return;
@@ -1049,9 +1256,13 @@ export class KnowledgeStore {
                         state.orphanEvents++;
                         return;
                     }
-                    const review = event.payload.actor === undefined
-                        ? { decision: event.payload.decision, at: event.at }
-                        : { decision: event.payload.decision, actor: event.payload.actor, at: event.at };
+                    const review = { decision: event.payload.decision, at: event.at };
+                    if (event.payload.actor !== undefined)
+                        review.actor = event.payload.actor;
+                    if (event.payload.note !== undefined)
+                        review.note = event.payload.note;
+                    if (event.payload.resolution !== undefined)
+                        review.resolution = event.payload.resolution;
                     const merged = validateLesson({
                         ...previous,
                         review,
@@ -1073,6 +1284,40 @@ export class KnowledgeStore {
                     }
                     return;
                 }
+                case 'lesson.batch': {
+                    const applied = [];
+                    const payload = event.payload;
+                    for (const item of payload.updates) {
+                        const previous = state.lessons.get(item.lessonId);
+                        if (previous === undefined || item.revision <= previous.revision) {
+                            state.orphanEvents++;
+                            continue;
+                        }
+                        const merged = validateLesson({
+                            ...previous,
+                            ...item.patch,
+                            id: previous.id,
+                            revision: item.revision,
+                            updatedAt: event.at,
+                        });
+                        if (merged.state !== previous.state && !canTransition(previous.state, merged.state)) {
+                            state.orphanEvents++;
+                            continue;
+                        }
+                        state.lessons.set(merged.id, merged);
+                        applied.push(merged);
+                    }
+                    if (!state.idempotency.has(event.idempotencyKey)) {
+                        const first = applied[0];
+                        const record = first === undefined
+                            ? { lessonId: payload.updates[0] === undefined ? '' : payload.updates[0].lessonId }
+                            : { lessonId: first.id, batch: applied, lessonIds: applied.map((lesson) => lesson.id) };
+                        if (event.requestHash !== undefined)
+                            record.requestHash = event.requestHash;
+                        state.idempotency.set(event.idempotencyKey, record);
+                    }
+                    return;
+                }
                 case 'evidence.add': {
                     const evidence = validateEvidence(event.payload);
                     state.evidence.set(evidence.id, evidence);
@@ -1106,6 +1351,8 @@ export class KnowledgeStore {
         if (sessionKey === undefined && hash === undefined)
             return undefined;
         for (const item of state.evidence.values()) {
+            if (input.verification === 'claimed' && item.verification === 'read')
+                continue;
             if (sessionKey !== undefined && evidenceSessionKey(item) === sessionKey)
                 return item;
             if (hash !== undefined && item.sourceHash === hash)
@@ -1118,12 +1365,12 @@ export class KnowledgeStore {
         if (!isRecord(input))
             throw new KnowledgeError('invalid', '证据输入必须是对象');
         const existing = this.findEvidenceByNaturalKey(state, input);
-        if (existing !== undefined)
+        if (existing !== undefined && !(existing.verification === 'claimed' && input.verification === 'read'))
             return existing;
         const now = new Date().toISOString();
         const raw = {
             schemaVersion: 1,
-            id: 'evd_' + randomUUID(),
+            id: existing?.id ?? 'evd_' + randomUUID(),
             kind: input.kind,
             observedAt: typeof input.observedAt === 'string' ? input.observedAt : now,
             summary: input.summary,
@@ -1137,6 +1384,8 @@ export class KnowledgeStore {
             raw.projectId = input.projectId;
         if (input.sourceHash !== undefined)
             raw.sourceHash = input.sourceHash;
+        if (input.verificationReason !== undefined)
+            raw.verificationReason = input.verificationReason;
         const evidence = this.maskEvidence(validateEvidence(raw));
         const natural = evidenceNaturalKey(evidence);
         const event = {
@@ -1194,13 +1443,23 @@ export class KnowledgeStore {
     maskLesson(lesson) {
         if (!this.mask)
             return lesson;
-        return {
+        const masked = {
             ...lesson,
             title: maskSecrets(lesson.title),
             action: maskSecrets(lesson.action),
             when: maskSecrets(lesson.when),
             exceptions: lesson.exceptions.map((item) => maskSecrets(item)),
         };
+        if (lesson.review.note !== undefined) {
+            const refs = [lesson.id, ...(lesson.review.resolution?.affectedIds ?? []), ...(lesson.review.resolution?.targetId ? [lesson.review.resolution.targetId] : [])];
+            masked.review = { ...lesson.review, note: maskSecrets(lesson.review.note, refs) };
+        }
+        if (lesson.feedback !== undefined)
+            masked.feedback = {
+                ...lesson.feedback,
+                recent: lesson.feedback.recent.map(item => ({ ...item, ...(item.note === undefined ? {} : { note: maskSecrets(item.note) }) })),
+            };
+        return masked;
     }
     maskEvidence(evidence) {
         if (!this.mask)
@@ -1295,6 +1554,7 @@ export class KnowledgeStore {
             badLines: counterNumber('badLines'),
             orphanEvents: counterNumber('orphanEvents'),
             unsupportedVersions: counterNumber('unsupportedVersions'),
+            skippedEvents: counterNumber('skippedEvents'),
             evidenceCount: counterNumber('evidenceCount'),
         };
         const lessonsRaw = raw.lessons;
@@ -1340,14 +1600,20 @@ export class KnowledgeStore {
                 const record = { lessonId: value.lessonId };
                 if (typeof value.requestHash === 'string')
                     record.requestHash = value.requestHash;
+                if (Array.isArray(value.lessonIds)) {
+                    record.lessonIds = value.lessonIds.filter((id) => typeof id === 'string');
+                }
                 idempotency.set(key, record);
             }
         }
         const serialized = {};
         for (const [key, entry] of idempotency) {
-            serialized[key] = entry.requestHash === undefined
-                ? { lessonId: entry.lessonId }
-                : { lessonId: entry.lessonId, requestHash: entry.requestHash };
+            const record = { lessonId: entry.lessonId };
+            if (entry.requestHash !== undefined)
+                record.requestHash = entry.requestHash;
+            if (entry.lessonIds !== undefined)
+                record.lessonIds = entry.lessonIds;
+            serialized[key] = record;
         }
         return {
             lessons,
@@ -1374,9 +1640,12 @@ export class KnowledgeStore {
         const prefixBytes = Math.min(size, PREFIX_HASH_BYTES);
         const idempotency = {};
         for (const [key, entry] of state.idempotency) {
-            idempotency[key] = entry.requestHash === undefined
-                ? { lessonId: entry.lessonId }
-                : { lessonId: entry.lessonId, requestHash: entry.requestHash };
+            const record = { lessonId: entry.lessonId };
+            if (entry.requestHash !== undefined)
+                record.requestHash = entry.requestHash;
+            if (entry.lessonIds !== undefined)
+                record.lessonIds = entry.lessonIds;
+            idempotency[key] = record;
         }
         return {
             offset: size,
@@ -1389,6 +1658,7 @@ export class KnowledgeStore {
                 badLines: state.badLines,
                 orphanEvents: state.orphanEvents,
                 unsupportedVersions: state.unsupportedVersions,
+                skippedEvents: state.skippedEvents,
                 evidenceCount: state.evidence.size,
             },
             idempotency,

package/lib/knowledge.d.ts

@@ -4,6 +4,15 @@ export type LessonKind = 'preference' | 'procedure' | 'pitfall' | 'fact';
 export type LessonState = 'candidate' | 'usable' | 'disputed' | 'stale' | 'rejected';
 /** 审阅结论。 */
 export type ReviewDecision = 'unreviewed' | 'accepted' | 'rejected';
+/** 解析 / 冲突处理的可选痕迹（事件与经验都带得下；旧数据没有也合法）。 */
+export interface LessonReviewResolution {
+    /** prefer | drop | merge 等；不强制枚举，由 tools 层约定。 */
+    kind: string;
+    targetId?: string;
+    affectedIds?: string[];
+}
+/** 审阅备注最大长度；超出截断而不是报错。 */
+export declare const REVIEW_NOTE_MAX_LENGTH = 500;
 /** 一条可复用经验。 */
 export interface Lesson {
     schemaVersion: 1;
@@ -36,7 +45,11 @@ export interface Lesson {
         decision: ReviewDecision;
         actor?: string;
         at?: string;
+        note?: string;
+        resolution?: LessonReviewResolution;
     };
+    /** 使用反馈独立于审阅和证据；只保留最近 20 次明细，事件流保留历史。 */
+    feedback?: LessonFeedback;
     createdAt: string;
     updatedAt: string;
     lastValidatedAt?: string;
@@ -44,6 +57,15 @@ export interface Lesson {
     supersedes?: string[];
     conflictIds: string[];
 }
+export interface LessonFeedback {
+    useful: number;
+    notApplicable: number;
+    recent: Array<{
+        vote: 'useful' | 'not-applicable';
+        at: string;
+        note?: string;
+    }>;
+}
 /** 一条证据：只存脱敏摘要 + 定位信息。 */
 export interface Evidence {
     schemaVersion: 1;
@@ -58,6 +80,8 @@ export interface Evidence {
     /** read=插件读到原记录；claimed=仅模型声称。 */
     verification: 'read' | 'claimed';
     sourceHash?: string;
+    /** 插件生成的核验结果；不是模型给出的保证。 */
+    verificationReason?: string;
 }
 /** dream_learn / 迁移的输入。 */
 export interface LessonInput {
@@ -110,6 +134,8 @@ export type KnowledgeEvent = {
         decision: ReviewDecision;
         actor?: string;
         state: LessonState;
+        note?: string;
+        resolution?: LessonReviewResolution;
     };
 } | {
     schemaVersion: 1;
@@ -119,6 +145,20 @@ export type KnowledgeEvent = {
     idempotencyKey: string;
     requestHash?: string;
     payload: Evidence;
+} | {
+    schemaVersion: 1;
+    id: string;
+    at: string;
+    kind: 'lesson.batch';
+    idempotencyKey: string;
+    requestHash?: string;
+    payload: {
+        updates: Array<{
+            lessonId: string;
+            revision: number;
+            patch: Partial<Lesson>;
+        }>;
+    };
 };
 /** 知识层错误码：invalid=数据不合法；revision=乐观锁不符；duplicate=重复；io=读写/锁失败。 */
 export declare class KnowledgeError extends Error {