@a9i5k4/dsh-auto-memory 2.5.3 → 3.0.1

package/lib/note-status.js

@@ -0,0 +1,196 @@
+/**
+ * 结论层状态（G3）· **纯函数核心** —— 零 IO、零副作用、可单测。
+ *
+ * ⚠️ **状态：形态候选，未接线**（2026-09-19）
+ *   本模块只提供**判定与格式**能力；**没有任何调用方**，因此不产生任何写入。
+ *   写盘接线必须等 `G3-DISK-FORMAT-GAP-20260919.md` §4 的 **F1/F2 拍板**后才做：
+ *     F1 = 状态行的磁盘语法；F2 = 「显式声明取代」的模型侧写法。
+ *   理由（误判代价不对称）：漏判 = 维持现状（可接受）；**误判 = 有效结论被当废纸**。
+ *
+ * ── 为什么需要本模块（设计稿未覆盖的缺口）─────────────────────────
+ * `MEMORY-GOVERNANCE-20260917.md` §8.1 断言「地基已存在，只差写入方」。
+ * 实施前核查证明：该断言**只对内存索引列成立**；`status` 的**磁盘表示完全不存在**：
+ *   ① `memory-anchor.js:28` `MARKER_RE` 是**严格锚定** ⇒ 锚点行加不了属性；
+ *   ② 行首含 `MARKER_OPEN` 但不匹配 ⇒ `malformed-anchor` **冲突**（:214）⇒ 写入被拒（storage-manage:181）；
+ *   ③ 全仓**零处**从磁盘读 `status`（`statusOf` 无任何生产者）；
+ *   ④ sidecar 不能承载（`memory-writer.js:434` 明示其为**可重建的派生数据**）。
+ *   ⇒ 必须先定一个**磁盘形态**，这正是 F1 要拍的板。
+ *
+ * ── 形态选择（方案 A/B 已排除，见 GAP 文档 §3）────────────────────
+ *   方案 A（锚点加属性）❌ 撞 ①②，属契约级改动；
+ *   方案 B（独立状态文件）❌ 违反 S10.4「不新建状态源」；
+ *   **方案 C（条目正文内保留行）✅ 采用** —— 状态归条目自身，零语法风险，用户可读。
+ *
+ * ── ★ 关键实现约束：不得污染 L0 ──────────────────────────────────
+ * `extractL0Pre` 规则③（`l0-extract.js:385`）会把**所有非标题行压平**成 L0。
+ * 若状态行留在正文里，无标题条目的 L0 会变成「⚠已作废…」⇒ **检索质量被污染**
+ * （与 M2.5a 修的是同一类问题）。
+ * ⇒ 消费方**必须先 `stripStatusLinePre(body)` 再抽取 L0**，或经 `statusOf` 提供状态。
+ */
+
+/** 状态行开标记。**刻意不复用** `MARKER_OPEN`（`<!-- memory:`）—— 复用会撞锚点契约。 */
+export const NOTE_STATUS_OPEN_V1 = '<!-- dsh-status:'
+
+/**
+ * 状态行语法（F1 候选 (a)：HTML 注释形态）。
+ *
+ * 为什么用 HTML 注释而非裸行 `status: superseded`：
+ *   ① 与仓储既有习俗一致（锚点本身也是 HTML 注释）；
+ *   ② 与正文散文**零碰撞**（裸行会被「正文恰好以 status: 开头」误命中）；
+ *   ③ 渲染后不可见，不干扰人读 Markdown。
+ * 属性值支持裸词与双引号两种写法（reason 含空格时用引号）。
+ */
+const NOTE_STATUS_RE = /^<!--\s*dsh-status:\s*(current|superseded|retracted)\s*((?:\w+=(?:"[^"]*"|[^\s"]+)\s*)*)-->$/
+
+/** 属性解析：`by=mem_xxx` / `reason="含空格 的原因"`。 */
+const NOTE_STATUS_ATTR_RE = /(\w+)=(?:"([^"]*)"|([^\s"]+))/g
+
+/** 只认本仓 id 形态，防把任意文本拼进状态（同 R4-A 的 `supersededMarkPre` 纪律）。 */
+const MEMORY_ID_RE = /^mem_[0-9a-f]{32}$/
+
+/** 三态取值域（与 `l0-extract.js` 的 `L0_STATUSES` 同源；此处独立声明以免循环依赖）。 */
+export const NOTE_STATUSES_V1 = Object.freeze(['current', 'superseded', 'retracted'])
+
+/** reason 上限：状态行是**元数据**不是正文，超长即视为脏数据。 */
+export const NOTE_STATUS_REASON_MAX_V1 = 120
+
+/**
+ * 渲染状态行（**纯函数**）。
+ *
+ * `current` ⇒ 返回 `''`（**当前态无需落盘**：缺失即默认 current，少写字节、少一处漂移源）。
+ * 未知 status / 非法 id ⇒ 返回 `''`（**fail-closed**：宁可不写，绝不写错 —— 与消费侧同纪律）。
+ *
+ * @param {string} status current | superseded | retracted
+ * @param {{supersededBy?:string, reason?:string}} [opts]
+ * @returns {string} 状态行（含 `\n` 时不带）；不可渲染时为空串
+ */
+export function renderStatusLinePre(status, opts = {}) {
+  try {
+    if (status !== 'superseded' && status !== 'retracted') return ''
+    let line = NOTE_STATUS_OPEN_V1 + ' ' + status
+    const by = opts && opts.supersededBy ? String(opts.supersededBy).trim() : ''
+    if (MEMORY_ID_RE.test(by)) line += ' by=' + by
+    const reason = opts && opts.reason
+      ? String(opts.reason).replace(/[\r\n]+/g, ' ').replace(/--+>/g, '').trim().slice(0, NOTE_STATUS_REASON_MAX_V1)
+      : ''
+    if (reason) line += ' reason="' + reason.replace(/"/g, "'") + '"'
+    return line + ' -->'
+  } catch (_) { return '' }   // fail-soft：渲染失败绝不抛（与 supersededMarkPre 同纪律）
+}
+
+/**
+ * 解析单行状态。非状态行 ⇒ `null`（不抛、不猜）。
+ *
+ * 返回对象**只含合法字段**：非法 `by` 被丢弃（不写进结果），未知属性忽略。
+ *
+ * @param {string} line 单行文本
+ * @returns {{status:string, supersededBy?:string, reason?:string}|null}
+ */
+export function parseStatusLinePre(line) {
+  try {
+    const s = String(line == null ? '' : line).trim()
+    if (!s) return null
+    const m = NOTE_STATUS_RE.exec(s)
+    if (!m) return null
+    const out = { status: m[1] }
+    NOTE_STATUS_ATTR_RE.lastIndex = 0
+    let a
+    while ((a = NOTE_STATUS_ATTR_RE.exec(m[2] || '')) !== null) {
+      const key = a[1]
+      const val = a[2] !== undefined ? a[2] : a[3]
+      if (key === 'by') {
+        if (MEMORY_ID_RE.test(String(val || ''))) out.supersededBy = String(val)
+      } else if (key === 'reason') {
+        const r = String(val || '').replace(/[\r\n]+/g, ' ').trim().slice(0, NOTE_STATUS_REASON_MAX_V1)
+        if (r) out.reason = r
+      }
+    }
+    return out
+  } catch (_) { return null }
+}
+
+/**
+ * 从**条目正文**解析状态。
+ *
+ * 语义：**最后一个**状态行胜出（后写覆盖先写 —— 状态是"当前值"不是"历史轨迹"）。
+ * 无状态行 ⇒ `{status:'current'}`（与索引层「缺失即默认」口径完全一致）。
+ *
+ * @param {string} body 条目正文（不含锚点行）
+ * @returns {{status:string, supersededBy?:string, reason?:string}}
+ */
+export function statusOfBodyPre(body) {
+  const s = String(body == null ? '' : body)
+  const lines = s.split(/\r?\n/)
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const hit = parseStatusLinePre(lines[i])
+    if (hit) return hit
+  }
+  return { status: 'current' }
+}
+
+/**
+ * 剥掉状态行，返回**可安全送往 L0 抽取**的正文。
+ *
+ * ★ 这是本模块存在的主要理由之一：不剥 ⇒ 无标题条目的 L0 会被状态行污染（见文件头注释）。
+ * 纪律：只删**整行**匹配的；行内出现（如正文引用该语法）**保持原样**交由
+ * `checkReservedSyntaxInContent` 一类守卫处理，本函数不做静默改写。
+ *
+ * @param {string} body
+ * @returns {string}
+ */
+export function stripStatusLinePre(body) {
+  const s = String(body == null ? '' : body)
+  if (!s.includes(NOTE_STATUS_OPEN_V1)) return s
+  return s.split(/\r?\n/).filter((ln) => parseStatusLinePre(ln) === null).join('\n')
+}
+
+/**
+ * 追加状态行到正文末尾（**纯函数**，不写盘）。
+ *
+ * 约束（见文件头）：
+ *   - 先剥旧状态行 ⇒ 结果是**幂等**的（同参数重复调用不叠加）；
+ *   - 只追加在**末尾**，绝不前置（前置会污染 L0 规则②/③）；
+ *   - `current` ⇒ 只剥不写。
+ *
+ * @param {string} body
+ * @param {string} status
+ * @param {{supersededBy?:string, reason?:string}} [opts]
+ * @returns {string}
+ */
+export function withStatusLinePre(body, status, opts = {}) {
+  const base = stripStatusLinePre(body).replace(/[\r\n\s]+$/, '')
+  const line = renderStatusLinePre(status, opts)
+  if (!line) return base
+  return base + '\n' + line
+}
+
+/**
+ * ★F2 候选 (b)：从**正文**识别「显式声明取代」。
+ *
+ * ⚠️ 本函数**未接线**，且**不建议作为首个版本的唯一通路**：
+ *   用户裁定的门槛是「**(a) 只认显式声明**」，而**结构化参数**（F2 候选 a）才是最纯的显式声明；
+ *   从自然语言里正则识别**必然**存在误判，与「宁可漏判不可误判」冲突。
+ *   保留它用于：(b)/(c) 落地时作为**第二通路**，或作为「M2 lint 只报告」的输入。
+ *
+ * 判据（**双条件**，缺一不可 —— 这是保守性的关键）：
+ *   ① 出现取代**动作词**（取代/替换/作废/推翻/废弃 supersede）/ 或显式参数；
+ *   ② 同时出现**合法 memoryId**。
+ *   仅命中其一 ⇒ 返回 `null`（**只报告不标**）。
+ *
+ * @param {string} content 新写入的正文
+ * @returns {{target:string, evidence:string}|null}
+ */
+export function detectSupersedeIntentPre(content) {
+  try {
+    const s = String(content == null ? '' : content)
+    if (!s) return null
+    const ACT_RE = /(取代|替换|作废|废弃|推翻|supersede[sd]?|replaces?)/i
+    const ID_RE = /mem_[0-9a-f]{32}/g
+    const ids = s.match(ID_RE)
+    if (!ids || !ids.length) return null
+    if (!ACT_RE.test(s)) return null
+    // 去重保序；多目标时**不自动全标**（保守），交调用方逐个确认
+    const uniq = [...new Set(ids)]
+    return { target: uniq[0], evidence: (s.match(ACT_RE) || [''])[0] }
+  } catch (_) { return null }
+}

package/lib/procedure-observation.js

@@ -0,0 +1,48 @@
+import { createHash } from 'node:crypto'
+
+/** Episode-only rows cannot earn memory-ID evidence. Do not fabricate provenance or gates. */
+export function isObservationOnlyPre(p) {
+  if (!p || typeof p !== 'object') return false
+  if (p.observationOnly === true) return true
+  // Already validated/active, user-authored and deprecated history keeps its existing semantics.
+  if (p.origin === 'user' || (p.stage && !['observed', 'candidate'].includes(p.stage))) return false
+  return Array.isArray(p.sourceEpisodes) && p.sourceEpisodes.length > 0 &&
+    (!p.sourceMemoryIds || p.sourceMemoryIds.length === 0) &&
+    (!p.successCriteria || p.successCriteria.length === 0)
+}
+
+/** Additive metadata migration only; no change to identity, text, risk, evidence or stage. */
+export function normalizeProcedureObservationPre(p) {
+  if (!p || p.pinned || p.observationOnly !== undefined || !isObservationOnlyPre(p)) return p
+  return { ...p, observationOnly: true }
+}
+
+/** A title is not an identity. Rich and observation-only candidates must not contaminate each other. */
+export function procedureFingerprintPre(p) {
+  return JSON.stringify([p.title, p.origin === 'user' ? 'user' : 'agent', p.riskLevel || 'low',
+    isObservationOnlyPre(p), p.steps || [], p.preconditions || [], p.checks || [],
+    p.successCriteria || [], p.rollback || []])
+}
+
+export function matchingProcedurePre(rows, candidate) {
+  const fingerprint = procedureFingerprintPre(candidate)
+  return rows.find(p => p.stage !== 'deprecated' && procedureFingerprintPre(p) === fingerprint)
+}
+
+export function mergeProcedureSourcesPre(existing, candidate) {
+  // These are the only mergeable fields. In particular, never inherit a lower risk or approval.
+  existing.sourceMemoryIds = [...new Set([...(existing.sourceMemoryIds || []), ...(candidate.sourceMemoryIds || [])])]
+  existing.sourceEpisodes = [...new Set([...(existing.sourceEpisodes || []), ...(candidate.sourceEpisodes || [])])]
+}
+
+export function newProcedureIdentityPre(candidate, now, rows, idPrefix = 'proc_') {
+  const used = new Set(rows.map(p => p.procedureId))
+  for (let sequence = 0; sequence <= rows.length; sequence++) {
+    // 前缀必须与 procedure-store.js 的 PROCEDURE_ID_PREFIX(`proc_`)一致 ——
+    // 发布线为 `proc_`,由 tools/release.mjs 反向转换,故此处字面量按 pre 线写。
+    const digest = createHash('sha256').update(JSON.stringify(['procedure-v2', procedureFingerprintPre(candidate), now, sequence])).digest('hex')
+    const id = idPrefix + digest.slice(0, 32)
+    if (!used.has(id)) return id
+  }
+  throw new Error('procedure-id-exhausted')
+}

package/lib/procedure-store.js

@@ -1,3 +1,4 @@
+import { isObservationOnlyPre, normalizeProcedureObservationPre, matchingProcedurePre, mergeProcedureSourcesPre, newProcedureIdentityPre } from './procedure-observation.js'
 /**
  * M8-2 Procedural Store 纯核心(docs/proactive-associative-memory-system-map.html M-04 Procedural)。
  * 纯内存状态机,零 IO、零依赖(node:crypto 仅作确定性身份);持久化通过可注入 IO 接口,
@@ -82,6 +83,8 @@ export function validateProcedurePre(p) {
   if (!Array.isArray(p.rollback)) q.push('rollback')
   if (typeof p.createdAt !== 'number' || !Number.isFinite(p.createdAt)) q.push('createdAt')
   if (p.requiresApproval !== undefined && typeof p.requiresApproval !== 'boolean') q.push('requiresApproval')
+  // issue #30:observationOnly 可选字段,类型必须显式校验(否则脏值会静默通过校验层)。
+  if (p.observationOnly !== undefined && typeof p.observationOnly !== 'boolean') q.push('observationOnly')
   // 2026-08-28 Hermes 借鉴字段(可选,向后兼容旧快照):lastUsedAt/pinned/origin
   if (p.lastUsedAt !== undefined && (typeof p.lastUsedAt !== 'number' || !Number.isFinite(p.lastUsedAt))) q.push('lastUsedAt')
   if (p.pinned !== undefined && typeof p.pinned !== 'boolean') q.push('pinned')
@@ -103,6 +106,7 @@ export function validateProcedureCandidatePre(c) {
   if (c.preconditions !== undefined && !Array.isArray(c.preconditions)) p.push('preconditions')
   if (c.checks !== undefined && !Array.isArray(c.checks)) p.push('checks')
   if (c.rollback !== undefined && !Array.isArray(c.rollback)) p.push('rollback')
+  if (c.observationOnly !== undefined && typeof c.observationOnly !== 'boolean') p.push('observationOnly')
   if (p.length) return { ok: false, reason: 'invalid:' + p.join(',') }
   return { ok: true, candidate: c }
 }
@@ -129,7 +133,7 @@ export function createProcedureStorePre(opts = {}) {
   const stats = { observed: 0, candidates: 0, validated: 0, activated: 0, deprecated: 0, approvalAsked: 0 }
 
   function defaultProcedureId(title, createdAt) {
-    const h = createHash('sha256').update(['procedure-pre-v1', String(title), String(createdAt)].join('\u0000')).digest('hex')
+    const h = createHash('sha256').update(['procedure-v1', String(title), String(createdAt)].join('\u0000')).digest('hex')
     return PROCEDURE_ID_PREFIX + h.slice(0, 32)
   }
 
@@ -140,35 +144,42 @@ export function createProcedureStorePre(opts = {}) {
     if (!v.ok) return { ok: false, reason: v.reason }
     const c = v.candidate
     const now = nowFn()
-    // 去重: 同 title 已存在 → 返回 existing(不重复 observe)
-    const existing = procedures.find((p) => p.title === c.title && p.stage !== 'deprecated')
+    // issue #30 根因:旧实现按 `title` 去重 —— episode 自动观察出的"仅观察行"通常先建,
+    // 之后带真实步骤/成功判据的富候选**同名**时会被合并进观察行,而合并只拷贝证据源字段,
+    // 富候选的 steps/successCriteria **整体丢失** ⇒ promote() 永远卡在 `no-success-criteria`,
+    // 技能永远无法晋升。修法:① 先把历史行归一化出 observationOnly 标记;
+    // ② 用**指纹**(含 steps/criteria/rollback 等全部实质字段)匹配,仅观察行与富候选
+    // 指纹不同 ⇒ 各自独立成行,互不污染(标题不是身份)。
+    procedures = procedures.map(normalizeProcedureObservationPre)
+    const existing = matchingProcedurePre(procedures, c)
     if (existing) {
-      // 合并证据源
-      const seen = new Set(existing.sourceMemoryIds)
-      for (const id of c.sourceMemoryIds || []) if (!seen.has(id)) existing.sourceMemoryIds.push(id)
-      const seenEp = new Set(existing.sourceEpisodes)
-      for (const id of c.sourceEpisodes || []) if (!seenEp.has(id)) existing.sourceEpisodes.push(id)
+      mergeProcedureSourcesPre(existing, c)
+      existing.updatedAt = now
       void persist()
       return { ok: true, procedure: existing, merged: true }
     }
     const p = {
-      procedureId: defaultProcedureId(c.title, now),
+      procedureId: newProcedureIdentityPre(c, now, procedures, PROCEDURE_ID_PREFIX),
       title: c.title,
       stage: 'observed',
       riskLevel: c.riskLevel || 'low',
       requiresApproval: c.riskLevel === 'high' && gates.highRiskRequiresApproval,
-      sourceMemoryIds: c.sourceMemoryIds || [],
-      sourceEpisodes: c.sourceEpisodes || [],
-      preconditions: c.preconditions || [],
-      steps: c.steps,
-      checks: c.checks || [],
-      successCriteria: c.successCriteria || [],
-      rollback: c.rollback || [],
+      // issue #30:入参数组一律深拷一层,避免调用方后续改动把已入账记录改脏(与 PR#36 口径一致)。
+      sourceMemoryIds: [...new Set(c.sourceMemoryIds || [])],
+      sourceEpisodes: [...new Set(c.sourceEpisodes || [])],
+      preconditions: (c.preconditions || []).slice(),
+      steps: c.steps.slice(),
+      checks: (c.checks || []).slice(),
+      successCriteria: (c.successCriteria || []).slice(),
+      rollback: (c.rollback || []).slice(),
       createdAt: now,
       updatedAt: now,
       lastUsedAt: now,
       pinned: false,
       origin: c.origin === 'user' ? 'user' : 'agent',
+      // issue #30:纯 episode 观察行显式打标 —— 它没有 successCriteria,永远不该晋升,
+      // 也不该与富候选互相污染(此前无标记,只能靠 title 撞车后丢字段)。
+      ...(isObservationOnlyPre(c) ? { observationOnly: true } : {}),
       evidence: { seen: 0, read: 0, cite: 0, reuse: 0, success: 0, correction: 0, sessions: 0 },
       approved: c.riskLevel !== 'high',
     }
@@ -250,20 +261,46 @@ export function createProcedureStorePre(opts = {}) {
   /**
    * 晋升判定(M-04 元代码 promote 逐行)。
    * 返回 { decision: 'promote'|'keep'|'ask', procedure, reasonCodes }
+   *
+   * ★ T4（2026-09-19 用户拍板「让大模型来介入」）：新增第三个参数 `opts`。
+   *   `opts.authorizedBy`（如 'model'）= **模型显式授权**，用于跳过两条**统计证据门**
+   *   （`minSessionDiversity` / `minSuccessCount`）。
+   *
+   *   为什么需要它：这两条门是给**机械生成**的观察行用的防污染护栏 —— 它们靠"反复出现"累积证据。
+   *   但机械路径产出的条目 13/14 是空壳（`actions=['user','user','user']` 切出来的），
+   *   而**模型主动写出的技能**（带真 steps + successCriteria）**天生没有历史证据**，
+   *   若不放行则永远卡在 `diversity-below-3` ⇒ 模型通路等于白建。
+   *
+   *   **仍然保留的护栏（授权也不放行）**：
+   *     · `deprecated` 短路 —— 已弃用的不得复活；
+   *     · `isObservationOnlyPre` 短路 —— 结构上不该晋升的行，授权也拦；
+   *     · **`no-success-criteria` 必须有**（在下方）—— 没写验收标准的不算技能；
+   *     · `correction-rate` / `has-correction` —— 有纠正记录说明这流程是错的。
+   *   并**留痕**：`p.authorizedBy` + reasonCodes 追加 `model-authorized`，供审计与前端展示。
    */
-  function promote(procedureId, extraEvidence = {}) {
+  function promote(procedureId, extraEvidence = {}, opts = {}) {
     if (disposed) return { ok: false, reason: 'disposed' }
     const p = procedures.find((x) => x.procedureId === procedureId)
     if (!p) return { ok: false, reason: 'not-found' }
     if (p.stage === 'deprecated') return { ok: true, decision: 'keep', reasonCodes: ['deprecated'] }
+    // issue #30:纯 episode 观察行没有 successCriteria,本来就无法晋升;
+    // 显式短路并给出 `observation-only` 原因码,而不是让它落到下面报 `no-success-criteria`
+    // (后者会让使用者误以为"缺判据、补上就能晋升",其实是这行**结构上**不该晋升)。
+    // ★ T4:此短路**不受授权影响** —— 结构上不该晋升的行,模型授权也不放行。
+    if (isObservationOnlyPre(p)) return { ok: true, decision: 'keep', procedure: p, reasonCodes: ['observation-only'] }
 
     const ev = p.evidence
     const reason = []
+    const authorizedBy = opts && opts.authorizedBy ? String(opts.authorizedBy) : ''
+    if (authorizedBy) reason.push('model-authorized')
     // 跨会话多样性
     const diversity = extraEvidence.distinctSessions != null ? extraEvidence.distinctSessions : ev.sessions
     const successCount = extraEvidence.successCount != null ? extraEvidence.successCount : ev.success
-    if (diversity < gates.minSessionDiversity) { reason.push('diversity-below-' + gates.minSessionDiversity); return { ok: true, decision: 'keep', procedure: p, reasonCodes: reason } }
-    if (successCount < gates.minSuccessCount) { reason.push('success-below-' + gates.minSuccessCount); return { ok: true, decision: 'keep', procedure: p, reasonCodes: reason } }
+    // ★ T4:两条**统计证据门**在模型授权下跳过(见上方函数注释);未授权时行为逐字节不变。
+    if (!authorizedBy) {
+      if (diversity < gates.minSessionDiversity) { reason.push('diversity-below-' + gates.minSessionDiversity); return { ok: true, decision: 'keep', procedure: p, reasonCodes: reason } }
+      if (successCount < gates.minSuccessCount) { reason.push('success-below-' + gates.minSuccessCount); return { ok: true, decision: 'keep', procedure: p, reasonCodes: reason } }
+    }
     // correction 率
     const total = ev.seen + ev.read + ev.cite + ev.reuse + ev.success + ev.correction
     const corrRate = total > 0 ? ev.correction / total : 0
@@ -287,11 +324,68 @@ export function createProcedureStorePre(opts = {}) {
     // 晋升
     p.stage = 'validated'
     p.updatedAt = nowFn()
+    // ★ T4:授权晋升留痕 —— 前端与审计面必须能看出「这条是模型授权跳门进来的」,
+    //   否则日后无法区分「统计证据充分」与「模型判断值得」两种来源。
+    if (authorizedBy) p.authorizedBy = authorizedBy
     stats.validated++
     void persist()
     return { ok: true, decision: 'promote', procedure: p, reasonCodes: reason }
   }
 
+  /**
+   * ★R2（2026-09-20 用户要求「晋升原因必须看得见」）：**纯只读**晋升判定投影。
+   *
+   * 与 `promote()` 的关系：**逐行复制其门限判定，但不改任何状态**。
+   * 为什么不能直接调 `promote()`：它含真实副作用
+   * （`stats.approvalAsked++` / `p.stage='validated'` / `stats.validated++` / `persist()` 写盘），
+   * 在 `overview()` 这类只读轮询路径里调用会**污染统计并把候选悄悄提升**。
+   * ⇒ 只读面必须走本函数（用户 2026-09-18 冻结纪律）。
+   *
+   * ⚠️ 维护约定：改 `promote()` 的门限时**必须同步改这里**，否则前端会展示过时的判据。
+   * 两者的一致性由测试 `smoke-test-r2-promotion-pre.mjs` 用变异兜底。
+   *
+   * @returns {{ok:boolean, decision?:string, reasonCodes?:string[], detail?:object}}
+   */
+  function evaluatePromotion(procedureId) {
+    const p = procedures.find((x) => x.procedureId === procedureId)
+    if (!p) return { ok: false, reason: 'not-found' }
+    if (p.stage === 'deprecated') return { ok: true, decision: 'keep', reasonCodes: ['deprecated'] }
+    if (isObservationOnlyPre(p)) return { ok: true, decision: 'keep', reasonCodes: ['observation-only'] }
+    const ev = p.evidence || { seen: 0, read: 0, cite: 0, reuse: 0, success: 0, correction: 0, sessions: 0 }
+    const reason = []
+    const diversity = Number(ev.sessions) || 0
+    const successCount = Number(ev.success) || 0
+    const total = (Number(ev.seen) || 0) + (Number(ev.read) || 0) + (Number(ev.cite) || 0)
+      + (Number(ev.reuse) || 0) + successCount + (Number(ev.correction) || 0)
+    const corrRate = total > 0 ? (Number(ev.correction) || 0) / total : 0
+    // ⚠️ 顺序必须与 promote() **完全一致**（先返回的那个才决定前端文案）
+    if (diversity < gates.minSessionDiversity) {
+      reason.push('diversity-below-' + gates.minSessionDiversity)
+      return { ok: true, decision: 'keep', reasonCodes: reason, detail: { diversity, need: gates.minSessionDiversity } }
+    }
+    if (successCount < gates.minSuccessCount) {
+      reason.push('success-below-' + gates.minSuccessCount)
+      return { ok: true, decision: 'keep', reasonCodes: reason, detail: { successCount, need: gates.minSuccessCount } }
+    }
+    if (corrRate > gates.maxCorrectionRate) {
+      reason.push('correction-rate-' + corrRate.toFixed(2))
+      return { ok: true, decision: 'keep', reasonCodes: reason, detail: { corrRate, cap: gates.maxCorrectionRate } }
+    }
+    if (gates.maxContradictions === 0 && (Number(ev.correction) || 0) > 0) {
+      reason.push('has-correction')
+      return { ok: true, decision: 'keep', reasonCodes: reason, detail: { corrections: Number(ev.correction) || 0 } }
+    }
+    if (!p.successCriteria || !p.successCriteria.length) {
+      reason.push('no-success-criteria')
+      return { ok: true, decision: 'keep', reasonCodes: reason }
+    }
+    if (p.requiresApproval && !p.approved) {
+      reason.push('high-risk-awaiting-approval')
+      return { ok: true, decision: 'ask', reasonCodes: reason }
+    }
+    return { ok: true, decision: 'promote', reasonCodes: reason, detail: { diversity, successCount } }
+  }
+
   /** 激活: validated → active(可被召回)。 */
   function activate(procedureId) {
     const p = procedures.find((x) => x.procedureId === procedureId)
@@ -377,7 +471,9 @@ export function createProcedureStorePre(opts = {}) {
       const v = validateProcedurePre(p)
       if (!v.ok) continue
       if (p._sessions) { p._sessions = new Set(p._sessions); p.evidence.sessions = p._sessions.size }
-      procedures.push(v.procedure)
+      // issue #30:旧快照里没有 observationOnly 字段,恢复时按同一判据补齐
+      // (纯增量元数据迁移:不改身份/文本/风险/证据/阶段)。
+      procedures.push(normalizeProcedureObservationPre(v.procedure))
     }
     return { ok: true, restored: procedures.length }
   }
@@ -396,6 +492,8 @@ export function createProcedureStorePre(opts = {}) {
   }
 
   return {
+    // ★R2：只读判定投影（供 overview() 展示「为什么不能晋升」）
+    evaluatePromotion,
     observe, addEvidence, promote, activate, deprecate,
     touch, setPinned, applyAutomaticTransitions,
     query, activeProcedures, get, renderChecklist,

package/lib/python-setup.js

@@ -51,7 +51,7 @@ const PIP_DEPS_GPU_EXTRA = ['onnxruntime-gpu']
  *  历史上探针多要一个 torch,而 PIP_DEPS_CPU 从不装 torch → depsOk 恒 false,"全部就绪"永不出现。 */
 const DEPS_PROBE = 'import transformers, onnxruntime, numpy; print("deps-ok")'
 
-/** worker 侧 load_embedder 的档位名(m7_embedding_v1.PROVIDER_REAL_INT8);发布构建会把 -pre-v1 折成 -v1。 */
+/** worker 侧 load_embedder 的档位名(m7_embedding_v1.PROVIDER_REAL_INT8);发布构建会把 -v1 折成 -v1。 */
 const PROVIDER_ID_INT8 = 'bge-m3-onnx-int8-v1'
 /** dense 维度(BGE-M3 = 1024),写进 embedding-config.json 的 dimension。 */
 const EMBED_DIMENSION = 1024

package/lib/python-sidecar-client.js

@@ -80,9 +80,14 @@ export function createPythonSidecarClientPre(opts = {}) {
     if (disposed) return { ok: false, code: 'disposed' }
     if (child && (child.killed || (child.stdin && child.stdin.destroyed))) {
       // 上一个进程正在收尾(exit 事件未到):按已死处理,允许立即重生
+      // ★ issue #72 修复（2026-09-19）：此处必须**同时清空共享 buffer**。
+      //   旧实现只置 `epoch = null`（等 `:121` 的 exit 事件去清 buffer），但这条分支的前提正是
+      //   **exit 尚未到达** ⇒ 旧 worker 残留在 `buffer` 里的**无换行尾字节**会被新 worker 的首帧
+      //   `concat` 进去 ⇒ 该行 badJson ⇒ 应答被吞、请求白等到超时（默认 5000ms）。
       try { child.kill() } catch (_) {}
       child = null
       epoch = null
+      buffer = Buffer.alloc(0)   // ★ 丢弃旧代残尾,避免污染新 worker 首帧
     }
     if (child) return { ok: true }
     const scriptPath = String(resolveOpt('scriptPath') || defaultWorkerScriptPathPre())
@@ -161,7 +166,16 @@ export function createPythonSidecarClientPre(opts = {}) {
     const v = validateTransportFramePre(obj, { direction: 'in' })
     if (!v.ok) { stats.dropped.badEnvelope++; return }
     const frame = v.frame
-    if (epoch !== null && frame.workerEpoch !== epoch) { stats.dropped.staleEpoch++; return }
+    // ★ issue #72 修复（2026-09-19）：把入站 epoch 门从 **fail-open 改为 fail-closed**，与文件头 :7 的承诺一致。
+    //   旧写法 `if (epoch !== null && frame.workerEpoch !== epoch)`：**`epoch === null` 时整条门失效**，
+    //   任何合法 envelope 的帧都会穿透到 handler。epoch 为 null 的窗口是真实存在的
+    //   （未启动 / `exit` 事件已置 null 但旧 stdio 尚未排空 / restart 后到新 spawn 之间），
+    //   而 `activation_request` 上游 `context-host` **无二次校验**（同 activationId 有 dedup 兜底，
+    //   但**新 activationId 可穿透**）⇒ 幽灵激活。
+    //   新判据：**epoch 为空 ⇒ 一律丢弃**。理由：spawn 时同步赋 epoch（:91 `epoch = 'wk_' + …` 在
+    //   `spawn()` **之前**执行），出站帧也就带上了 epoch；对端 worker 以 `--expect-epoch` 自证身份后才回帧
+    //   ⇒ **正常路径不存在"帧先于 epoch"**，丢弃不会误伤任何合法流量。
+    if (!epoch || frame.workerEpoch !== epoch) { stats.dropped.staleEpoch++; return }
     if (frame.type === 'activation_request') {
       const activation = frame.payload && frame.payload.activation
       const aid = activation && activation.activationId
@@ -208,9 +222,18 @@ export function createPythonSidecarClientPre(opts = {}) {
     lastSentFrame = frame
     if (!child || !child.stdin || child.stdin.destroyed) return false
     const line = Buffer.from(JSON.stringify(frame) + '\n', 'utf8')
+    // ★ issue #75 CC-9 修复（2026-09-19）：**建帧时捕获当时的 child 引用**，flush 时校验身份。
+    //   旧实现：`writeChain.then(...)` 回调里解引用**当时的**模块级 `child` 变量。
+    //   若 writeChain 排队期间发生 respawn（`ensureStarted` 的收尾中重生 / `restart()`），
+    //   回调会读到**新** child，把**旧 epoch 的帧**写进新 worker 的 stdin ⇒ 对端回帧 epoch-mismatch
+    //   ⇒ 被判 `staleEpoch` 丢弃 ⇒ 该请求挂满自身超时（默认 5000ms）。
+    //   现改为闭包捕获 `sentTo`，且 flush 时 `child !== sentTo` 即视为该帧已随旧进程作废。
+    const sentTo = child
+    const sentStdin = child.stdin
     writeChain = writeChain.then(() => new Promise((done) => {
-      if (!child || !child.stdin || child.stdin.destroyed) { done(); return }
-      child.stdin.write(line, () => done())
+      if (child !== sentTo) { done(); return }   // 已换代：本帧作废，不得写入新 worker
+      if (!sentStdin || sentStdin.destroyed) { done(); return }
+      sentStdin.write(line, () => done())
     }))
     writeChain = writeChain.catch(() => {})
     return true
@@ -282,6 +305,9 @@ export function createPythonSidecarClientPre(opts = {}) {
     if (child) { try { child.kill() } catch (_) {} }
     child = null
     epoch = null
+    // ★ issue #72 修复：restart 同样要清 buffer（kill 后 exit 事件可能滞后，
+    //   旧代残尾会污染新 worker 首帧 ⇒ 该行 badJson ⇒ 请求白等到超时）。
+    buffer = Buffer.alloc(0)
     stats.restarts++
     void reason
   }