dsh-lite-memory 0.16.2 → 0.17.0

package/learning.js

@@ -22,12 +22,14 @@ export const LIMITS = {
   receipts: 64,
   samples: 4,
   checkpoints: 3,
+  callRules: 6,
+  organizerRules: 8,
 };
 
 export const FEEDBACK_TYPES = ['spec_change', 'execution_miss', 'task_exception', 'aspect_accept', 'artifact_accept', 'unclear'];
 export const LEARNING_STATES = ['pending', 'trial', 'active', 'paused'];
 export const PHASES = ['brief', 'theme', 'outline', 'script', 'shoot', 'edit', 'publish'];
-const ALLOWED_KEYS = new Set(['target', 'feedbackType', 'topicKey', 'currentText', 'title', 'summary', 'applicability', 'conditions', 'evidence', 'persistence']);
+const ALLOWED_KEYS = new Set(['target', 'feedbackType', 'topicKey', 'currentText', 'title', 'summary', 'applicability', 'conditions', 'evidence', 'persistence', 'sourceExcerpt']);
 
 const LONG_TERM = /以后|今后|长期|默认|每次都|每次|一直|统一|永远|从现在起|记住/;
 const EXPLICIT_ACCEPT = /可以了|就这样|这版|就用这版|用这版|挺好|满意|保留|沿用|继续用|定稿|通过/;
@@ -69,6 +71,10 @@ export function classifyFeedback(input) {
   if (has(EXPLICIT_ACCEPT, text) && !has(CORRECTION, text)) {
     return { worth: true, type: dimension ? 'aspect_accept' : 'artifact_accept', longTerm, explicitLongTerm: longTerm, exception, negative: false, dimension };
   }
+  /** 不是纠正句也可以立规范：“这个项目默认用 pnpm”这类声明本身就是长期要求。 */
+  if (longTerm && !exception) {
+    return { worth: true, type: 'spec_change', longTerm: true, explicitLongTerm: true, exception: false, negative, dimension };
+  }
   if (exception && has(CORRECTION, text)) {
     return { worth: true, type: 'task_exception', longTerm: false, explicitLongTerm: false, exception: true, negative, dimension };
   }
@@ -82,10 +88,40 @@ export function isLongTerm(text) {
   return has(LONG_TERM, String(text || ''));
 }
 
-/** 只有已绑定作品的人类反馈才进入整理候选；初始任务要求本身不是纠正。 */
-export function candidateFrom({ messages, anchor, sessionId, projectId, now } = {}) {
-  if (!anchor || !anchor.episodeId) return null;
-  if (!['active', 'continuable', 'proposed'].includes(anchor.status)) return null;
+const BOUND_STATUSES = ['active', 'continuable', 'proposed'];
+
+/**
+ * 一次整理运行能用到的身份只从调用方传入的上下文取：项目、会话、请求、作品、任务。
+ * 未绑定但带着 episodeId 的任务是「项目层候选」，不是「已绑定但作品失效」。
+ */
+export function runtimeContextOf(input = {}) {
+  const raw = input && typeof input === 'object' ? input : {};
+  const anchor = raw.anchor && typeof raw.anchor === 'object' ? raw.anchor : null;
+  const episodeId = String(anchor?.episodeId ?? raw.episodeId ?? '');
+  const status = String(anchor ? (anchor.status ?? '') : (raw.status ?? ''));
+  return {
+    projectId: String(raw.projectId ?? ''),
+    sessionId: String(raw.sessionId ?? ''),
+    requestId: String(raw.requestId ?? ''),
+    episodeId,
+    status,
+    bound: Boolean(episodeId) && BOUND_STATUSES.includes(status),
+    taskKind: String(anchor?.taskKind ?? raw.taskKind ?? ''),
+    seriesId: String(anchor?.seriesId ?? raw.seriesId ?? ''),
+    phase: String(anchor?.phase ?? raw.phase ?? ''),
+    anchorProjectId: String(anchor?.projectId ?? ''),
+    episodeUpdatedAt: String(anchor?.updatedAt ?? ''),
+  };
+}
+
+/** 人类反馈原文的短摘录；来源是历史消息，不重写。 */
+export function sourceExcerptOf(input, { max = 160 } = {}) {
+  const clean = String(input || '').replace(/\s+/g, ' ').trim();
+  if (!clean) return '';
+  return clean.length > max ? `${clean.slice(0, max)}…` : clean;
+}
+
+function humanFeedback(messages) {
   const ids = [];
   const texts = [];
   for (const message of Array.isArray(messages) ? messages : []) {
@@ -95,22 +131,73 @@ export function candidateFrom({ messages, anchor, sessionId, projectId, now } =
     ids.push(String(message.id ?? ''));
     texts.push(text);
   }
-  if (!texts.length) return null;
-  const text = texts.join('\n').slice(0, 1200);
+  return { ids: ids.filter(Boolean), text: texts.join('\n').slice(0, 1200) };
+}
+
+/**
+ * 有作品绑定就走作品候选；没有绑定、但属于同一项目的规范纠正或长期要求，
+ * 仍可形成 project 作用域的 pending 候选。跨项目一律不接收，也不把整个项目绑到单条栏目。
+ */
+export function candidateFrom({ messages, anchor, sessionId, projectId, now } = {}) {
+  /**
+   * 只有仍可用的作品绑定才算作品候选。任务状态里常常保留一个 unbound 的 episodeId，
+   * 旧逻辑见到 episodeId 就直接拒绝，导致这类项目永远走不到项目层候选。
+   */
+  const context = runtimeContextOf({ projectId, sessionId, anchor });
+  const bound = context.bound;
+  if (context.anchorProjectId && context.projectId && context.anchorProjectId !== context.projectId) return null;
+  const { ids, text } = humanFeedback(messages);
+  if (!text) return null;
   const cue = classifyFeedback(text);
   if (!cue.worth) return null;
+  const at = now || Date.now();
+  const messageIds = ids.slice(-8);
+  const sourceExcerpt = sourceExcerptOf(text);
+  if (bound) {
+    return {
+      projectId: context.projectId,
+      sessionId: context.sessionId,
+      scope: 'episode',
+      state: 'pending',
+      episodeId: context.episodeId,
+      taskKind: context.taskKind,
+      seriesId: context.seriesId,
+      phase: context.phase,
+      messageIds,
+      text,
+      sourceExcerpt,
+      cue,
+      expectedTarget: {
+        scope: 'episode',
+        projectId: context.projectId,
+        episodeId: context.episodeId,
+        ...(context.taskKind ? { taskKind: context.taskKind } : {}),
+        ...(context.seriesId ? { seriesId: context.seriesId } : {}),
+        ...(context.phase ? { phase: context.phase } : {}),
+      },
+      episodeUpdatedAt: context.episodeUpdatedAt,
+      at,
+    };
+  }
+  if (!context.projectId) return null;
+  /** 没有作品绑定时，规范纠正同样按项目候选收集；单次局部改动交给整理器判空，不再用电平词一刀切。 */
+  if (cue.type !== 'spec_change') return null;
   return {
-    projectId,
-    sessionId: String(sessionId || ''),
-    episodeId: anchor.episodeId,
-    taskKind: anchor.taskKind || '',
-    seriesId: anchor.seriesId || '',
-    phase: anchor.phase || '',
-    messageIds: ids.filter(Boolean).slice(-8),
+    projectId: context.projectId,
+    sessionId: context.sessionId,
+    scope: 'project',
+    state: 'pending',
+    episodeId: '',
+    taskKind: '',
+    seriesId: '',
+    phase: '',
+    messageIds,
     text,
+    sourceExcerpt,
     cue,
-    episodeUpdatedAt: anchor.updatedAt || '',
-    at: now || Date.now(),
+    expectedTarget: { scope: 'project', projectId, applicability: 'unresolved' },
+    episodeUpdatedAt: '',
+    at,
   };
 }
 
@@ -157,36 +244,222 @@ export function normalizeConditions(conditions) {
   return out.slice(0, 8);
 }
 
+const STATE_WEIGHT = { active: 3, trial: 2, pending: 1, paused: 0 };
+
+function gramsOf(input) {
+  const text = String(input || '').toLowerCase();
+  const out = new Set();
+  for (const word of text.match(/[a-z0-9_]+/g) || []) if (word.length >= 2) out.add(word);
+  for (const run of text.match(/[\u4e00-\u9fa5]+/g) || []) {
+    for (let index = 0; index + 1 < run.length; index += 1) out.add(run.slice(index, index + 2));
+  }
+  return out;
+}
+
+function relevanceOf(record, context) {
+  const query = String(context.query || '').toLowerCase();
+  const dimensions = (Array.isArray(context.dimensions) ? context.dimensions : [])
+    .map((value) => String(value || '').toLowerCase()).filter(Boolean);
+  const topicKey = String(record.topicKey || '').toLowerCase();
+  const conditions = normalizeConditions(record.conditions);
+  const hay = [
+    topicKey,
+    record.title || '',
+    record.summary || '',
+    record.body || '',
+    conditions.map((row) => `${row.key}=${row.value}`).join(' '),
+  ].join(' ').toLowerCase();
+  let score = 0;
+  if (topicKey && query) {
+    if (query.includes(topicKey)) score += 150;
+    else {
+      const shared = [...gramsOf(topicKey)].filter((gram) => query.includes(gram)).length;
+      if (shared) score += 90;
+    }
+  }
+  for (const dimension of dimensions) if (hay.includes(dimension)) score += 80;
+  const queryGrams = gramsOf(query);
+  const fieldWeights = [[record.title, 10], [record.summary, 6], [record.body, 4]];
+  for (const [text, weight] of fieldWeights) {
+    let hits = 0;
+    for (const gram of gramsOf(text)) if (queryGrams.has(gram)) hits += 1;
+    score += Math.min(hits, 6) * weight;
+  }
+  for (const row of conditions) {
+    if (row.key === 'taskKind' && context.taskKind && row.value === context.taskKind) score += 15;
+    else if (row.key === 'seriesId' && context.seriesId && row.value === context.seriesId) score += 15;
+    else if (row.key === 'phase' && context.phase && row.value === context.phase) score += 15;
+  }
+  return score;
+}
+
+/** 先按相关性和可用性排序，再截断；排序稳定可复现，不依赖输入顺序。 */
+export function rankRules(rules, context = {}) {
+  const rows = (Array.isArray(rules) ? rules : [])
+    .filter((record) => record && record.id)
+    .map((record, index) => ({
+      record,
+      index,
+      relevance: relevanceOf(record, context),
+      stateWeight: STATE_WEIGHT[record.learning?.state || record.state] ?? 1,
+      updated: String(record.updated || record.updatedAt || record.created || ''),
+      id: String(record.id),
+    }));
+  rows.sort((a, b) => b.relevance - a.relevance
+    || b.stateWeight - a.stateWeight
+    || b.updated.localeCompare(a.updated)
+    || a.id.localeCompare(b.id)
+    || a.index - b.index);
+  return rows.map((row) => row.record);
+}
+
+export function selectRules(rules, context = {}) {
+  const limit = Number(context.limit || LIMITS.organizerRules);
+  return rankRules(rules, context).slice(0, Math.max(1, limit));
+}
+
+/**
+ * 整理器可见规则：先按状态、最近使用、更新时间稳定排序，再取上限；
+ * 不能先 slice 再排序，否则真正可用的旧经验会被输入顺序挤掉。
+ */
+export function orderOrganizerRules(rules, { limit = LIMITS.organizerRules } = {}) {
+  const cap = Math.max(1, Number(limit) || LIMITS.organizerRules);
+  const rows = (Array.isArray(rules) ? rules : [])
+    .filter((record) => record && record.id)
+    .map((record, index) => {
+      const lastUsed = Date.parse(record.lastUsedAt || record.learning?.lastUsedAt || record.learning?.usedAt || '');
+      const updated = Date.parse(record.learning?.updatedAt || record.updatedAt || record.updated || '');
+      return {
+        record,
+        index,
+        stateWeight: STATE_WEIGHT[record.learning?.state || record.state] ?? 1,
+        lastUsed: Number.isFinite(lastUsed) ? lastUsed : 0,
+        updated: Number.isFinite(updated) ? updated : 0,
+        id: String(record.id),
+      };
+    });
+  rows.sort((a, b) => b.stateWeight - a.stateWeight
+    || b.lastUsed - a.lastUsed
+    || b.updated - a.updated
+    || a.id.localeCompare(b.id)
+    || a.index - b.index);
+  return rows.slice(0, cap).map((row) => row.record);
+}
+
 /** 构造一次受限调用输入：无工具、无前台历史，只有身份、少量规则和反馈映射。 */
+/** 明确长期要求本身就是可信收集信号：整理器返回空时至少落一条规则，不让它无声消失。 */
+export function pendingChangeFrom(feedback = {}) {
+  const text = String(feedback.text || '').replace(/\r/g, '').trim();
+  if (!text) return null;
+  const lines = text.split('\n').map((line) => line.trim()).filter(Boolean).slice(0, 6);
+  const currentText = lines.join('\n').slice(0, 240);
+  if (!currentText) return null;
+  const first = (lines[0] || currentText).split(/[，。！？；]/)[0].trim();
+  const topicKey = String(feedback.cue?.dimension || first || currentText).slice(0, 60);
+  return {
+    target: 'new',
+    feedbackType: 'spec_change',
+    topicKey,
+    currentText,
+    applicability: 'all_in_scope',
+    conditions: [],
+    evidence: ['u0'],
+    persistence: 'project_candidate',
+    /** 摘录从候选一路带到提交路径，模型返回空时也不丢来源。 */
+    sourceExcerpt: String(feedback.sourceExcerpt || sourceExcerptOf(text)).slice(0, 160),
+  };
+}
+
+/**
+ * 收集与展示共用的准入判断；启发式推断只能得到「待确认候选」，
+ * 不会因为写进存储就变成用户确认，除非候选本身带着明确的确认标记。
+ */
+export function admissionOf(candidate, runtime = {}, purpose = 'collect') {
+  const mode = String(purpose || 'collect');
+  if (!['collect', 'display'].includes(mode)) return { ok: false, reason: '用途不认' };
+  if (!candidate || typeof candidate !== 'object') return { ok: false, reason: '没有候选' };
+  const context = runtimeContextOf({ ...(runtime || {}), projectId: runtime?.projectId ?? candidate.projectId, sessionId: runtime?.sessionId ?? candidate.sessionId });
+  if (!context.projectId) return { ok: false, reason: '缺少项目身份' };
+  if (candidate.projectId && String(candidate.projectId) !== context.projectId) return { ok: false, reason: '候选不属于这个项目' };
+  const cue = candidate.cue && typeof candidate.cue === 'object' ? candidate.cue : classifyFeedback(candidate.text);
+  if (!cue?.worth) return { ok: false, reason: '反馈不值得检查' };
+  const scope = candidate.scope === 'project' ? 'project' : 'episode';
+  if (scope === 'episode') {
+    if (!context.bound) return { ok: false, reason: '作品绑定已经失效', scope };
+    if (candidate.episodeId && String(candidate.episodeId) !== context.episodeId) return { ok: false, reason: '候选不属于这期作品', scope };
+  } else {
+    if (context.bound) return { ok: false, reason: '有作品绑定时不走项目候选', scope };
+    if (cue.type !== 'spec_change') return { ok: false, reason: '项目候选只收规范纠正', scope };
+  }
+  const confirmed = candidate.confirmed === true || runtime?.confirmed === true;
+  return {
+    ok: true,
+    purpose: mode,
+    scope,
+    projectId: context.projectId,
+    episodeId: scope === 'episode' ? context.episodeId : '',
+    cueType: cue.type,
+    longTerm: Boolean(cue.explicitLongTerm),
+    confirmed,
+    requiresUserConfirmation: !confirmed,
+    /** 写入后仍是待确认候选，不冒充已确认的长期规则。 */
+    persistence: 'project_candidate',
+    visibility: 'candidate',
+  };
+}
+
 export function buildCallInput({ projectId, episodeId, taskKind, seriesId, phase, feedback, rules, ranges, maxBytes = LIMITS.inputBytes } = {}) {
+  const context = runtimeContextOf({ projectId, episodeId, taskKind, seriesId, phase });
   const refs = { feedback: {}, rules: {} };
   const source = (Array.isArray(rules) ? rules : []).filter((record) => record && record.id);
-  /** 用户这次纠正涉及的规则先入输入：固定取前 6 条会把真正相关的旧经验挤掉。 */
+  /** 先按本次反馈的相关性排序，再取前几条：固定取前 6 条会把真正相关的旧经验挤掉。 */
   const dimension = String(feedback?.cue?.dimension || '');
-  const prioritized = dimension
-    ? [...source.filter((record) => `${record.title || ''}${record.summary || ''}${record.body || ''}`.includes(dimension)),
-      ...source.filter((record) => !`${record.title || ''}${record.summary || ''}${record.body || ''}`.includes(dimension))]
-    : source;
-  refs.feedback.u0 = feedback.messageIds[0] || '';
+  const prioritized = selectRules(source, {
+    query: feedback?.text || '',
+    dimensions: dimension ? [dimension] : [],
+    taskKind: context.taskKind,
+    seriesId: context.seriesId,
+    phase: context.phase,
+    limit: LIMITS.callRules,
+  });
+  const messageIds = (Array.isArray(feedback?.messageIds) ? feedback.messageIds : [])
+    .map((id) => String(id || '')).filter(Boolean).slice(-8);
+  const sourceExcerpt = String(feedback?.sourceExcerpt || sourceExcerptOf(feedback?.text || '')).slice(0, 160);
+  refs.feedback.u0 = messageIds[0] || '';
   const project = {
-    projectId: bounded(projectId, 80),
-    episodeId: bounded(episodeId, 80),
-    ...(taskKind ? { taskKind } : {}),
-    ...(seriesId ? { seriesId } : {}),
-    ...(phase ? { phase } : {}),
+    projectId: bounded(context.projectId, 80),
+    ...(context.episodeId ? { episodeId: bounded(context.episodeId, 80) } : { scope: 'project' }),
+    ...(context.taskKind ? { taskKind: context.taskKind } : {}),
+    ...(context.seriesId ? { seriesId: context.seriesId } : {}),
+    ...(context.phase ? { phase: context.phase } : {}),
   };
   const rangesInput = {
     taskKind: (ranges?.taskKinds || []).slice(0, 8),
     seriesId: (ranges?.series || []).slice(0, 8),
     phase: PHASES.slice(),
   };
-  const system = '你是项目记忆整理器，只输出 JSON。只能依据给定反馈修改已有规则或新建一条项目规则；不得调用工具，不得输出 JSON 之外的文字。没有可确定的长期变化时输出 {"changes":[]}。';
+  const system = '你是项目记忆整理器，只输出 JSON。只能依据给定反馈修改已有规则或新建一条项目规则；不得调用工具，不得输出 JSON 之外的文字。'
+    + '可复用的做法、偏好、禁止项，或对作品的可迁移纠正，都应落成规则；反馈没有说“以后”也可以新建，保存为待确认候选，由用户决定。'
+    + '同一主题已有规则时更新那条，不要新建重复规则；验收和执行检查点只能挂到已有规则。'
+    + '只改某一处文案、换一次值这类单次局部改动不建规则。'
+    + '只有明确仅限这一次、没有可执行内容、或无法判断时才输出 {"changes":[]}。';
   const feedbackHead = {
-    type: feedback.cue?.type || 'unclear',
-    longTerm: Boolean(feedback.cue?.explicitLongTerm),
+    type: feedback?.cue?.type || 'unclear',
+    longTerm: Boolean(feedback?.cue?.explicitLongTerm),
+    scope: feedback?.scope === 'project' ? 'project' : 'episode',
+    ...(feedback?.cue?.dimension ? { dimension: feedback.cue.dimension } : {}),
+    ...(sourceExcerpt ? { sourceExcerpt } : {}),
+    ...(messageIds.length ? { messageIds } : {}),
   };
   const tail = {
-    allowed: { conditions: view.CONDITION_KEYS, ranges: rangesInput, maxChanges: LIMITS.maxChanges, execution_miss: '仅已有规则，currentText 写检查点', artifact_accept: '仅已有规则，记验收样例' },
+    allowed: {
+      conditions: view.CONDITION_KEYS,
+      ranges: rangesInput,
+      maxChanges: LIMITS.maxChanges,
+      execution_miss: '仅已有规则，currentText 写检查点',
+      artifact_accept: '仅已有规则，记验收样例',
+      existing: '同主题改 r0，不新建重复规则',
+    },
     output: {
       changes: [{
         target: 'r0 或 new', feedbackType: FEEDBACK_TYPES, topicKey: '短主题键', currentText: '当前可执行规范', applicability: 'all_in_scope|conditional|unresolved', conditions: [{ key: 'taskKind', value: 'video' }], evidence: ['u0'], persistence: 'project_candidate',
@@ -228,7 +501,7 @@ export function buildCallInput({ projectId, episodeId, taskKind, seriesId, phase
     inputRules.push(row);
     prompt = next;
   }
-  return { system, prompt, messages: [{ role: 'user', content: prompt }], refs, rules: inputRules, bytes: Buffer.byteLength(system) + Buffer.byteLength(prompt) };
+  return { system, prompt, messages: [{ role: 'user', content: prompt }], refs, rules: inputRules, bytes: Buffer.byteLength(system) + Buffer.byteLength(prompt), sourceExcerpt, messageIds };
 }
 /** 严格解析：截断、工具调用、额外字段、超限都整批拒绝，不做第二次修复调用。 */
 export function parseOutput(text, { finish, refs, rules, ranges } = {}) {
@@ -277,6 +550,22 @@ export function validateChange(change, { refs, rules, ranges } = {}) {
     revision: byRef.get(target).revision,
     conditions: byRef.get(target).conditions,
   };
+  /** 反馈类型决定能改什么：例外、检查点、认可都不能借机重写规范。 */
+  if (checkpointOnly && (change.topicKey !== undefined || change.title !== undefined
+    || change.summary !== undefined || change.applicability !== undefined || change.conditions !== undefined)) {
+    return { ok: false, reason: '执行检查点只记录检查点，不改规范' };
+  }
+  if (change.feedbackType === 'aspect_accept') {
+    if (target === 'new') return { ok: false, reason: '认可只能挂到匹配的已有规则' };
+    if (change.currentText !== undefined || change.topicKey !== undefined || change.title !== undefined
+      || change.summary !== undefined || change.applicability !== undefined) {
+      return { ok: false, reason: '认可只记录验收，不改规范' };
+    }
+    if (change.conditions !== undefined
+      && JSON.stringify(normalizeConditions(change.conditions)) !== JSON.stringify(normalizeConditions(existing?.conditions))) {
+      return { ok: false, reason: '认可条件与目标规则不一致' };
+    }
+  }
   if (change.persistence !== undefined && change.persistence !== 'project_candidate') return { ok: false, reason: '持久化方式不认' };
   const topicKey = change.topicKey === undefined ? (existing || sampleOnly ? undefined : '') : String(change.topicKey || '').trim();
   if (!existing && !sampleOnly && !topicKey) return { ok: false, reason: '新规则缺少主题键' };
@@ -319,6 +608,7 @@ export function validateChange(change, { refs, rules, ranges } = {}) {
       ...(applicability !== undefined ? { applicability } : {}),
       ...(conditions !== undefined ? { conditions } : {}),
       evidence,
+      ...(change.sourceExcerpt !== undefined ? { sourceExcerpt: bounded(change.sourceExcerpt, 160) } : {}),
     },
   };
 }
@@ -406,22 +696,59 @@ export function addCheckpoint(learning, checkpoint = {}) {
   return next;
 }
 
-/** 状态只看证据强度：明确长期要求或两个独立作品才 active；条件不确定就 pending。 */
+const NON_NORM_TYPES = new Set(['execution_miss', 'artifact_accept', 'aspect_accept']);
+
+/**
+ * 状态只看证据强度：明确长期要求或两个独立作品才 active；条件不确定就 pending。
+ * 例外/含糊/验收/执行检查点不形成长期规范；目标或规范变了，旧证据立即失效。
+ */
 export function nextLearningState({ existing, change, evidence, now, specChanged = false } = {}) {
   const at = new Date(now || Date.now()).toISOString();
   const learning = existing?.learning ? JSON.parse(JSON.stringify(existing.learning)) : { state: 'pending', supportedEpisodeIds: [], evidence: [] };
   const priorState = LEARNING_STATES.includes(learning.state) ? learning.state : 'pending';
-  /** 规范正文或适用条件变了：旧证据不再支持新规范，只保留本次这一条。 */
-  const episodes = specChanged ? [] : (Array.isArray(learning.supportedEpisodeIds) ? learning.supportedEpisodeIds.slice() : []);
+  const feedbackType = change?.feedbackType || '';
+  learning.updatedAt = at;
+  learning.lastFeedbackType = feedbackType || learning.lastFeedbackType || '';
+  /** 这些反馈只补充验收或检查点，不抬升状态，也不产生长期规范。 */
+  if (NON_NORM_TYPES.has(feedbackType) || feedbackType === 'task_exception' || feedbackType === 'unclear') {
+    if (!existing) learning.state = 'pending';
+    return learning;
+  }
+  const targetChanged = Boolean(change?.id && existing?.id && String(change.id) !== String(existing.id));
+  /** 规范正文、适用条件或目标对象变了：旧证据不再支持新规范，只保留本次这一条。 */
+  const reset = specChanged === true || targetChanged;
+  const episodes = reset ? [] : (Array.isArray(learning.supportedEpisodeIds) ? learning.supportedEpisodeIds.slice() : []);
   if (evidence?.episodeId && !episodes.includes(evidence.episodeId)) episodes.push(evidence.episodeId);
-  const anchors = specChanged ? [] : (Array.isArray(learning.evidence) ? learning.evidence.slice() : []);
+  const anchors = reset ? [] : (Array.isArray(learning.evidence) ? learning.evidence.slice() : []);
   if (evidence?.episodeId && !anchors.some((row) => row.episodeId === evidence.episodeId)) anchors.push(evidence);
   learning.supportedEpisodeIds = episodes.slice(-LIMITS.evidence);
   learning.evidence = anchors.slice(-LIMITS.evidence).map((row) => ({ ...row }));
-  learning.updatedAt = at;
-  learning.lastFeedbackType = change?.feedbackType || learning.lastFeedbackType || '';
+  if (reset) {
+    learning.evidenceResetAt = at;
+    learning.evidenceResetReason = targetChanged ? 'target_changed' : 'spec_changed';
+    delete learning.samples;
+  }
+  const sourceRefs = Array.isArray(evidence?.messageIds) ? evidence.messageIds : [];
+  if (evidence?.episodeId || evidence?.sourceExcerpt || sourceRefs.length) {
+    const excerpt = bounded(evidence?.sourceExcerpt || evidence?.excerpt || '', 160);
+    const messageIds = (Array.isArray(evidence?.messageIds) ? evidence.messageIds : []).slice(-3).map((id) => bounded(id, 80));
+    if (excerpt) learning.sourceExcerpt = excerpt;
+    learning.sourceRefs = [...(Array.isArray(learning.sourceRefs) ? learning.sourceRefs : []), {
+      excerpt,
+      messageIds,
+      episodeId: String(evidence?.episodeId || ''),
+      feedbackType,
+      at,
+    }].slice(-LIMITS.evidence);
+    learning.binding = {
+      targetId: String(change?.id || existing?.id || 'new'),
+      baseRevision: Number(existing?.revision || 0),
+      messageIds,
+      at,
+    };
+  }
   if (change?.currentText) learning.lastText = change.currentText;
-  if (priorState === 'paused' && !specChanged && !Boolean(evidence?.explicitLongTerm)) {
+  if (priorState === 'paused' && !reset && !Boolean(evidence?.explicitLongTerm)) {
     learning.state = 'paused';
     return learning;
   }
@@ -458,6 +785,58 @@ export function nextLearningState({ existing, change, evidence, now, specChanged
   return learning;
 }
 
+/** 过期 pending 只是待复核失效，不销毁候选内容；可重新唤起。 */
+export function candidateExpired(learning, now) {
+  const at = now || Date.now();
+  if (!learning || learning.state !== 'pending' || !learning.createdAt) return false;
+  return at - Date.parse(learning.createdAt) > LIMITS.trialMs;
+}
+
+/** 只数还有效的 pending；过期候选不占名额。 */
+export function pendingCount(entries, now) {
+  const at = now || Date.now();
+  return (Array.isArray(entries) ? entries : []).filter((entry) => {
+    const learning = entry && entry.learning ? entry.learning : entry;
+    return learning && learning.state === 'pending' && !candidateExpired(learning, at);
+  }).length;
+}
+
+/** 重新唤起过期候选：换新的待确认窗口，但不伪造新的证据。 */
+export function reviveCandidate(learning, { now } = {}) {
+  if (!learning) return learning;
+  const at = now || Date.now();
+  const next = JSON.parse(JSON.stringify(learning));
+  next.state = 'pending';
+  next.createdAt = new Date(at).toISOString();
+  next.updatedAt = next.createdAt;
+  next.recoveredAt = next.createdAt;
+  delete next.trialUntil;
+  delete next.blockedReason;
+  delete next.pausedAt;
+  delete next.pausedBy;
+  return next;
+}
+
+/**
+ * 准入顺序：先算目标状态，再看上限。pending 满了不能挡住会直接变成 trial/active 的更新，
+ * 已有规则的修订也永不因配额被挡。
+ */
+export function admitChange({ existing, change, evidence, now, explicitLongTerm = false, pending = 0, rules = 0 } = {}) {
+  const merged = mergeChange(existing || null, change, { now });
+  const learning = nextLearningState({
+    existing: existing || { learning: merged.learning },
+    change,
+    evidence: { ...evidence, explicitLongTerm },
+    specChanged: merged.specChanged === true,
+    now,
+  });
+  const next = { merged, learning };
+  if (existing) return { ok: true, ...next };
+  if (Number(rules) + 1 > LIMITS.rules) return { ok: false, reason: '项目实验规则已经到上限' };
+  if (learning.state === 'pending' && Number(pending) >= LIMITS.pending) return { ok: false, reason: '待确认候选已经到上限' };
+  return { ok: true, ...next };
+}
+
 export function pauseLearning(learning, { by = 'feedback', reason = 'feedback_pending', now } = {}) {
   const next = learning ? JSON.parse(JSON.stringify(learning)) : { supportedEpisodeIds: [], evidence: [] };
   next.state = 'paused';
@@ -480,15 +859,43 @@ export function resumeLearning(learning, { by = 'management', now } = {}) {
 }
 
 /** 频次先在项目锁内扣，失败也计数；超限返回延后原因。 */
-export function quota(learning, { episodeId, now } = {}) {
+/**
+ * 滚动窗口内的调用次数：以最近一次调用时间判断，不依赖 recent 数组；
+ * 关开实验只清在途观察（recent），attempts 里的已用额度不会被开关重置。
+ */
+export function attemptWindowOf(learning, { now } = {}) {
   const at = now || Date.now();
   const ledger = learning && typeof learning === 'object' ? learning : {};
   const attempts = ledger.attempts && typeof ledger.attempts === 'object' ? ledger.attempts : {};
-  const recent = (Array.isArray(ledger.recent) ? ledger.recent : []).filter((value) => at - Date.parse(value) < LIMITS.windowMs);
-  const episodeCount = Number(attempts[episodeId]?.count || 0);
-  if (episodeCount >= LIMITS.attemptsPerEpisode) return { ok: false, reason: 'episode_limit', episodeCount, projectCount: recent.length };
-  if (recent.length >= LIMITS.attemptsPerProject) return { ok: false, reason: 'project_limit', episodeCount, projectCount: recent.length };
-  return { ok: true, episodeCount, projectCount: recent.length };
+  const recent = (Array.isArray(ledger.recent) ? ledger.recent : [])
+    .filter((value) => Number.isFinite(Date.parse(value)) && at - Date.parse(value) < LIMITS.windowMs);
+  let calls = 0;
+  let rows = 0;
+  for (const row of Object.values(attempts)) {
+    if (!row || typeof row !== 'object') continue;
+    const lastAt = Date.parse(row.lastAt || '');
+    /** 老数据没有时间戳时按仍在窗口内算，宁可少放一次也不放宽额度。 */
+    if (Number.isFinite(lastAt) && at - lastAt >= LIMITS.windowMs) continue;
+    calls += Number(row.count || 0);
+    rows += 1;
+  }
+  return { at, recent: recent.length, rows, calls, projectCount: Math.max(recent.length, calls) };
+}
+
+export function quota(learning, { episodeId, now } = {}) {
+  const window = attemptWindowOf(learning, { now });
+  const attempts = learning && learning.attempts && typeof learning.attempts === 'object' ? learning.attempts : {};
+  /** 项目层候选没有作品身份，store 用 project:<key> 记账：只受项目滚动额度约束。
+   *  同一批反馈只算一次的职责在调用方（operationId 重放），不能拿“每期两次”把整个项目卡死。 */
+  const projectScoped = !episodeId || String(episodeId).startsWith('project:');
+  const episodeCount = projectScoped ? 0 : Number(attempts[episodeId]?.count || 0);
+  if (!projectScoped && episodeCount >= LIMITS.attemptsPerEpisode) {
+    return { ok: false, reason: 'episode_limit', episodeCount, projectCount: window.projectCount };
+  }
+  if (window.projectCount >= LIMITS.attemptsPerProject) {
+    return { ok: false, reason: 'project_limit', episodeCount, projectCount: window.projectCount };
+  }
+  return { ok: true, episodeCount, projectCount: window.projectCount };
 }
 
 export function recordAttempt(learning, { episodeId, now } = {}) {
@@ -569,17 +976,18 @@ export function effectSummary(learning) {
   };
 }
 
-/** 到期的 trial/paused 按边界清理；active 与用户固定规范不走 TTL。 */
+/** 到期的 trial/paused 按边界清理；过期 pending 只标可恢复，不销毁；active 与用户固定规范不走 TTL。 */
 export function lifecycle(entries, now) {
   const at = now || Date.now();
   const purge = [];
   const paused = [];
+  const recoverable = [];
   for (const entry of Array.isArray(entries) ? entries : []) {
     const learning = entry?.learning;
     if (!learning || entry.origin !== 'project_evolution' || learning.pinned === true) continue;
-    if (learning.state === 'pending' && learning.createdAt && at - Date.parse(learning.createdAt) > LIMITS.trialMs) purge.push(entry.id);
+    if (learning.state === 'pending' && candidateExpired(learning, at)) recoverable.push(entry.id);
     else if (learning.state === 'trial' && learning.trialUntil && at - Date.parse(learning.trialUntil) > 0) paused.push(entry.id);
     else if (learning.state === 'paused' && learning.pausedAt && at - Date.parse(learning.pausedAt) > LIMITS.pausedMs) purge.push(entry.id);
   }
-  return { purge, paused };
+  return { purge, paused, recoverable };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-lite-memory",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "description": "On-demand memory for the DeepSeek Harness: nothing in the system prompt, one muted line only when something is saved, hit or suggested.",
   "type": "module",
   "main": "index.js",
@@ -8,7 +8,7 @@
     "dsh": ">=0.1.5"
   },
   "scripts": {
-    "test": "node test/store.test.mjs && node test/state.test.mjs && node test/view.test.mjs && node test/anchor.test.mjs && node test/recall.test.mjs && node test/evolution-read.test.mjs && node test/lexical.test.mjs && node test/control.test.mjs && node test/learning.test.mjs && node test/scenario.test.mjs && node test/crossing.test.mjs && node test/client.test.mjs && node test/contract.test.mjs",
+    "test": "node test/store.test.mjs && node test/state.test.mjs && node test/view.test.mjs && node test/anchor.test.mjs && node test/recall.test.mjs && node test/evolution-read.test.mjs && node test/lexical.test.mjs && node test/control.test.mjs && node test/learning.test.mjs && node test/scenario.test.mjs && node test/crossing.test.mjs && node test/runtime-context.test.mjs && node test/client.test.mjs && node test/palace.test.mjs && node test/contract.test.mjs",
     "bench": "node bench/bench.mjs",
     "bench:evolution": "node bench/evolution.mjs"
   },
@@ -33,6 +33,9 @@
     "README.md",
     "TRIGGERS.md",
     "docs",
+    "!docs/competitive-notes.md",
+    "!docs/ha-audit.md",
+    "!docs/ROADMAP.md",
     "LICENSE",
     "bench",
     "test"