@a9i5k4/dsh-auto-memory 2.5.3 → 3.0.0

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',
     }
@@ -256,6 +267,10 @@ export function createProcedureStorePre(opts = {}) {
     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`
+    // (后者会让使用者误以为"缺判据、补上就能晋升",其实是这行**结构上**不该晋升)。
+    if (isObservationOnlyPre(p)) return { ok: true, decision: 'keep', procedure: p, reasonCodes: ['observation-only'] }
 
     const ev = p.evidence
     const reason = []
@@ -377,7 +392,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 }
   }

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/rerank-host.js

@@ -0,0 +1,160 @@
+/**
+ * rerank-host-pre —— P4 精排多级档位 + 有界异步窗口(2026-09-16, rerank_host_v1)。
+ *
+ * 权威依据: MASTER-PLAN-3.0.md §Phase 4 (H2 按实测重写) + TODO-GRAPH V2-P4 卡。
+ * 实测推翻方案假设(留痕): bge-reranker-v2-m3 P95 37.4 秒(50 对/题, RSS 3.84GB);
+ *   qwen3-reranker-0.6b P95 8.8 秒(小样本探针 10 对/题, RSS 4.95GB, 不可与 bge 直接比);
+ *   收益真实: recall@1 0.739 → 0.898(bge); cross-encoder 模型已下载; 真实缺口 = GPU 版 torch
+ *   (torch 2.13.0+cpu)与快档量化产物。⇒ 精排不得同步等待, 只能走**有界异步窗口**。
+ *
+ * 设计(卡内 v2 修正, 逐条对应):
+ *  - 多级档位(用户裁定): 'off' | 'fast'(int8+CPU, 未就绪=不可用) | 'enthusiast'(完整模型+GPU)。
+ *    档位只决定"是否允许排精排任务", 一期本地无 GPU torch / 无量化产物 ⇒ fast/enthusiast 均
+ *    fail closed 降级为粗排(绝不阻塞前台、绝不发出模型请求)。
+ *  - 一分钟 = 有界后台窗口: 从**入队时**起算含排队与计算, **到期不续命**; 本轮立即用现有排序;
+ *    后台完成只进有界结果缓存, 不改本轮 envelope、不再次 emit; 下一请求重新生成 requestKey,
+ *    仅 inputKey 完全匹配才复用, 且重跑当轮检查; 没有下一轮就过期, 不主动制造模型请求。
+ *  - 运行隔离: 精排必须走独立懒加载 worker 角色(注入 opts.rerankFn), 不得占用稠密/索引 worker;
+ *    全机最多一个精排任务在跑(busy 门), 忙时继续粗排。
+ *  - 资源门 T5-5R: 任务超清理宽限未被取消/完成 ⇒ 调 opts.killFn 终止并释放; 期间稠密查询照常。
+ *  - T5-6R: 本模块不产出任何"异步注入收益"口径 — 结果只进缓存; 零复用就是零复用。
+ *
+ * 纯主机侧状态机, 模型调用经 opts.rerankFn 注入(测试可控), 零 fs/零网络。
+ */
+
+export const RERANK_HOST_VERSION = 'rerank_host_v1'
+
+/** 有界异步窗口: 从入队起算(毫秒), 含排队与计算; 到期不续命。 */
+export const RERANK_WINDOW_MS_V1 = 60000
+/** 登记的清理宽限: 超窗后仍允许 killFn 在此宽限内终止进程。 */
+export const RERANK_KILL_GRACE_MS_V1 = 5000
+/** 缓存上限(条): 有界结果缓存, LRU 逐出。 */
+export const RERANK_CACHE_MAX_V1 = 16
+
+/** 档位解析: 'off'/'fast'/'enthusiast' 之外一律按 off(fail closed)。 */
+export function resolveRerankTierPre(raw) {
+  const s = String(raw || '').toLowerCase()
+  if (s === 'fast' || s === 'enthusiast') return { tier: s, active: false, reason: 'tier-not-provisioned' }
+  if (s === 'off') return { tier: 'off', active: false, reason: 'tier-off' }
+  return { tier: 'off', active: false, reason: 'invalid-tier' }
+}
+
+/**
+ * inputKey: 精排复用的完全匹配键 — 查询 + 排序输入 + miv 的规范化哈希。
+ * 任一身份字段变化 ⇒ 键不同 ⇒ 不复用(T5-3R)。
+ */
+export function computeRerankInputKeyPre({ query, orderedIds, memoryIndexVersion }) {
+  return sha256Hex(JSON.stringify([String(query || ''), JSON.stringify(Array.isArray(orderedIds) ? orderedIds.map(String) : []), String(memoryIndexVersion || '')]))
+}
+
+function sha256Hex(s) {
+  // 纯 JS sha256 避免引入 node:crypto 依赖面 — 复用 djb2 式双哈希足够做键(非安全用途),
+  // 但为确定性可审计, 用 FNV-1a 64 位两次盐化。
+  let h1 = 0x811c9dc5, h2 = 0x811c9dc5
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i)
+    h1 = ((h1 ^ c) * 0x01000193) >>> 0
+    h2 = ((h2 ^ (c + i)) * 0x01000193) >>> 0
+  }
+  return h1.toString(16).padStart(8, '0') + h2.toString(16).padStart(8, '0')
+}
+
+/**
+ * 创建精排主机(每引擎一份)。
+ * opts: {
+ *   tier: 'off'|'fast'|'enthusiast',
+ *   now?: () => ms(测试可注入),
+ *   rerankFn?: async ({query, ordered}) => number[]  // 独立 worker 角色; 懒加载由调用方注入
+ *   killFn?: () => void                               // T5-5R: 终止精排进程并释放
+ * }
+ */
+export function createRerankHostPre(opts = {}) {
+  const now = typeof opts.now === 'function' ? opts.now : () => Date.now()
+  const resolved = resolveRerankTierPre(opts.tier)
+  const stats = { enqueued: 0, reused: 0, expiredDrops: 0, killed: 0, completed: 0, busyRejects: 0, tierRejects: 0 }
+  /** Map<inputKey, {at, scores}> — 有界结果缓存(只缓存, 不推送)。 */
+  const cache = new Map()
+  let running = null // {inputKey, startedAt, done}
+
+  function pruneExpired() {
+    const t = now()
+    for (const [k, v] of cache) {
+      if (t - v.at > RERANK_WINDOW_MS_V1) { cache.delete(k); stats.expiredDrops++ }
+    }
+  }
+
+  /**
+   * 请求一次精排机会(每轮 recall 调用一次)。
+   * 返回 {mode, scores?, reason?}:
+   *   mode='reuse'  — 缓存命中(窗口内 + inputKey 完全匹配); 调用方把 scores 并进本轮展示。
+   *   mode='skip'   — 档位关/未就绪/无 worker/忙/无下一轮价值 ⇒ 本轮粗排, 不发模型请求。
+   *   mode='accepted' — 已入队(有界异步窗口起算); 本轮立即返回(粗排序不变)。
+   * **本轮同步路径绝不等待精排**(T5-3R: 前台先返回, 后台完成只进缓存)。
+   */
+  function offerRerankPre({ query, orderedIds, memoryIndexVersion, requestKey }) {
+    pruneExpired()
+    const tier = resolveRerankTierPre(opts.tier)
+    if (tier.tier === 'off') { stats.tierRejects++; return { mode: 'skip', reason: 'tier-off' } }
+    // fast/enthusiast 的可用性由"是否注入了独立 worker"决定(运行隔离: rerankFn 即懒加载 worker 角色)。
+    // 环境未供给(GPU torch 缺/量化产物缺) ⇒ 调用方不注入 rerankFn ⇒ 这里 fail closed 走粗排。
+    if (typeof opts.rerankFn !== 'function') { stats.tierRejects++; return { mode: 'skip', reason: 'no-worker' } }
+    const inputKey = computeRerankInputKeyPre({ query, orderedIds, memoryIndexVersion })
+    const hit = cache.get(inputKey)
+    if (hit && now() - hit.at <= RERANK_WINDOW_MS_V1) {
+      // T5-4R: 复用前调用方必须重跑当轮状态/fv2/冷却/预算检查 — 本模块只担保 inputKey 完全匹配。
+      stats.reused++
+      return { mode: 'reuse', scores: hit.scores, inputKey }
+    }
+    if (running) { stats.busyRejects++; return { mode: 'skip', reason: 'busy', inputKey } }
+    // 入队: 一期全机最多一个精排任务; 有界窗口从入队起算, 到期不续命。
+    stats.enqueued++
+    const startedAt = now()
+    const job = { inputKey, startedAt, requestKey: String(requestKey || '') }
+    running = job
+    Promise.resolve()
+      .then(() => opts.rerankFn({ query, ordered: Array.isArray(orderedIds) ? orderedIds.map(String) : [] }))
+      .then((scores) => {
+        // 到期不续命: 完成时已超窗 ⇒ 丢弃(没有下一轮就过期, 不制造请求)。
+        if (now() - startedAt > RERANK_WINDOW_MS_V1) { stats.expiredDrops++; return }
+        // 缓存条目记入队时刻(卡内口径: 窗口从入队起算, 不是完成时刻 — 否则慢计算等于续命)。
+        cache.set(inputKey, { at: startedAt, scores: Array.isArray(scores) ? scores : [] })
+        if (cache.size > RERANK_CACHE_MAX_V1) {
+          const oldest = [...cache.entries()].sort((a, b) => a[1].at - b[1].at)[0]
+          if (oldest) cache.delete(oldest[0])
+        }
+        stats.completed++
+      })
+      .catch(() => { /* fail soft: 精排失败不影响粗排 */ })
+      .finally(() => { if (running === job) running = null })
+    return { mode: 'accepted', inputKey }
+  }
+
+  /**
+   * T5-5R: 精排忽略取消/卡死 ⇒ 调用方在登记的清理宽限内调用; 终止进程并释放占用。
+   * 返回 {killed:boolean}。稠密查询与本主机其余路径不受影响。
+   */
+  function killRunningRerankPre() {
+    if (!running) return { killed: false }
+    running = null
+    stats.killed++
+    try { if (typeof opts.killFn === 'function') opts.killFn() } catch (_) {}
+    return { killed: true }
+  }
+
+  /** 是否存在超窗未完成的运行任务(调用方据此在宽限内 kill)。 */
+  function isRunningBeyondWindowPre() {
+    return !!(running && now() - running.startedAt > RERANK_WINDOW_MS_V1 + RERANK_KILL_GRACE_MS_V1)
+  }
+
+  function debugView() {
+    pruneExpired()
+    return {
+      version: RERANK_HOST_VERSION, tier: resolved.tier, active: resolved.active,
+      running: running ? { inputKey: running.inputKey, elapsedMs: now() - running.startedAt, beyondWindow: isRunningBeyondWindowPre() } : null,
+      cacheSize: cache.size, stats,
+      windowMs: RERANK_WINDOW_MS_V1, killGraceMs: RERANK_KILL_GRACE_MS_V1,
+    }
+  }
+
+  return { offerRerankPre, killRunningRerankPre, isRunningBeyondWindowPre, debugView }
+}

package/lib/rules-layer.js

@@ -0,0 +1,261 @@
+/**
+ * 规则层抽取（rules_layer_v1）—— P6A 的"分类"部分（Phase 6 拆分中的 6A）。
+ *
+ * 2026-09-14 建立（P0 第五步）。**它解决的是用户最痛的病之一**：
+ *   注入开场白原来把所有记忆统一降格为「只是背景事实与规则参考」（`lib/index.js` 的
+ *   `DEFAULT_PROMPT_LAYERS.snapshotHead`），**规则与资料混在一句措辞里** ⇒ 模型注意力不落在规矩上。
+ *   用户原话：「这个 just for reference 说得太轻了，模型注意力没有在这上面。」
+ *
+ * **本模块只做一件事**：从记忆文本里**认出规则类条目**，把它们与参考类分开。
+ * 措辞分层（不同引导语）与节奏（每轮在场）由调用方负责。
+ *
+ * **真源纪律（v2 修正，必须遵守）**：用户级规则＝**既有用户级记忆文件**（`~/.dsh/memory/MEMORY.md`）
+ * 里的类型化规则，**不是新增 `RULES.md`**。`ROUND3 §2.3` 记录了我方曾在两处写了两个真源，
+ * 被 GPT 抓出。若将来真要独立真源，必须补迁移/去重/旧模式读取/回滚四类测试。
+ *
+ * **两级判定**（T7-4 的"双保险"，v2 修正后的形态）：
+ *   ① **结构化前缀**（高置信）：`【用户硬性规则…】` 这类显式标记 —— 这是既有记忆的真实形态
+ *      （实测：`~/.dsh/memory/MEMORY.md` 首条即 `【用户硬性规则 - 文件编码】`）。
+ *   ② **约束语汇**（中置信）：`严禁` / `绝不` / `必须` / `不得` 等。
+ *
+ *   ⚠️ **v2 明确纠正过我方原设计**：不能"命中关键词就无条件升级为规则"。
+ *   反例（GPT 给）：`"文档写着必须重启"`、`"曾经要求必须 X 但已取消"` —— 这类是**描述**不是**要求**。
+ *   故本模块对 ② 类的结果标注 `confidence:'medium'` 并**保留原文里的引用/历史语境标记**
+ *   （`引文` / `已取消` / `据文档` 等），由调用方决定是否只作为「待确认候选」。
+ *   本模块**不把中置信项冒充高置信**——那正是 T7-4 要防的误报。
+ *
+ * **依赖边界（如实标注，不宣称已保证）**：本模块保证的是"规则段被**注入函数**产出且不受节流与裁剪"。
+ *   "模型**真的收到了**"取决于宿主最终请求 messages 的确认（`MASTER-PLAN-3.0.md §7` 的 **U6**，
+ *   尚未具备）⇒ **不得**据此宣称"规则的遵守问题已解决"（T7-7 的纪律）。
+ *
+ * S9 合规：零 IO、零依赖、纯函数、无网络/无 LLM/无子进程/无 await。UTF-8 无 BOM。
+ */
+
+export const RULES_LAYER_VERSION = 'rules_layer_v1'
+
+/**
+ * ★P6B（2026-09-15 · 用户裁定开工）：日志行内 kind 标记 —— 规则分类的**持久化**落点。
+ *
+ * 权威依据：`TODO-GRAPH.html` V2-P6B 卡 points[1]（"分类时机：不做独立 LLM 调用，
+ * memory_log 本来就在本轮内由模型直接写，顺手打 kind 标记＝零额外成本"）+ crit[1]（T7-5）。
+ *
+ * **形态选行内标记** `- HH:MM [kind:rule] 内容`：日志是 append-only 纯文本，行内标记
+ * 可被本模块的条目切分生态直接消费，且重启/迁移不丢（不依赖任何 sidecar）。
+ * kind 作**可选参数**（缺省 fact）：不传时写入行与旧版逐字节一致（新旧并存 + 开关回退纪律）。
+ */
+export const LOG_KINDS_V1 = Object.freeze(['rule', 'preference', 'fact', 'todo'])
+
+/** 行内标记的正则形态（渲染/解析两侧共用，不各写一套）。 */
+export const LOG_KIND_TAG_RE_V1 = /\s*\[kind:(rule|preference|fact|todo)\]\s*/
+
+/** 结构化前缀（高置信）：既有用户级记忆的真实形态。 */
+export const RULE_MARKERS_V1 = Object.freeze([
+  '【用户硬性规则', '【硬性规则', '【规则】', '【必须遵守', '【禁止', '【用户规则',
+])
+
+/** 约束语汇（中置信）—— 单靠它**不足以**判定为规则（见文件头 T7-4 说明）。 */
+export const RULE_CONSTRAINT_WORDS_V1 = Object.freeze([
+  '严禁', '绝不', '必须', '不得', '禁止', '务必', '一律', '永远不', '不要再', '不准',
+])
+
+/**
+ * 引用/历史语境标记：出现这些 ⇒ 该段说的是"别处这么写"或"曾经如此"，
+ * **不是**当前有效的规则要求 ⇒ 降级为 `candidate`（待确认候选），不得自动取得不可裁地位。
+ * 这是 v2 §3.3（Q7 第 2 条）给的反例在代码里的落点。
+ */
+export const RULE_DESCRIPTION_MARKERS_V1 = Object.freeze([
+  '据文档', '文档写着', '文档说', '曾经', '已取消', '已废弃', '不再要求', '原要求', '旧规则', '据说',
+])
+
+/** 条目切分锚点：与 `l0-extract.js` 的记忆锚点完全一致（不另立一套）。 */
+const MEM_ANCHOR_LINE_RE = /^<!--\s*memory:(mem_[0-9a-f]{32})\s*-->$/
+
+/** 条目内的日期小节（`## 2026-08-14`）——既有记忆文件的实际结构。 */
+const DATE_SECTION_RE = /^##\s*\d{4}-\d{2}-\d{2}\s*$/
+
+const clean = (s) => String(s == null ? '' : s)
+
+/**
+ * 把记忆文本按锚点切成条目（保持既有文件结构语义：无锚点的前置内容归入首条）。
+ *
+ * @param {string} text 用户级/工作区级记忆文件全文
+ * @returns {Array<{id:string, anchorLine:number, text:string, lines:string[]}>}
+ */
+export function splitMemoryEntriesPre(text) {
+  const src = clean(text).replace(/^\uFEFF/, '')
+  if (!src.trim()) return []
+  const lines = src.split('\n')
+  const out = []
+  let cur = null
+  for (let i = 0; i < lines.length; i++) {
+    const m = MEM_ANCHOR_LINE_RE.exec(lines[i].replace(/\r$/, ''))
+    if (m) {
+      if (cur) out.push(cur)
+      cur = { id: m[1], anchorLine: i + 1, lines: [] }
+      continue
+    }
+    if (cur) cur.lines.push(lines[i])
+  }
+  if (cur) out.push(cur)
+  if (!out.length) {
+    // 无锚点文件（旧格式）⇒ 整篇算一条，不丢内容
+    return [{ id: '', anchorLine: 0, lines, text: src.trim() }]
+  }
+  return out.map((e) => ({ id: e.id, anchorLine: e.anchorLine, lines: e.lines, text: e.lines.join('\n').trim() }))
+}
+
+/** 单条文本的规则分类（返回置信度与理由，不抛异常）。 */
+function classifyText(rawText) {
+  const text = clean(rawText)
+  if (!text.trim()) return { kind: 'reference', confidence: 'none', reasons: ['空内容'] }
+  const marker = RULE_MARKERS_V1.find((k) => text.includes(k))
+  if (marker) {
+    return { kind: 'rule', confidence: 'high', reasons: ['结构化前缀 ' + marker] }
+  }
+  const words = RULE_CONSTRAINT_WORDS_V1.filter((w) => text.includes(w))
+  if (!words.length) return { kind: 'reference', confidence: 'none', reasons: ['无规则标记与约束语汇'] }
+  const desc = RULE_DESCRIPTION_MARKERS_V1.filter((w) => text.includes(w))
+  if (desc.length) {
+    // ★ v2 修正的落点：含"必须"但是**描述/引文**，不得自动升级为规则
+    return {
+      kind: 'candidate', confidence: 'low',
+      reasons: ['约束语汇（' + words.slice(0, 3).join('/') + '）但含引用/历史语境（' + desc.slice(0, 3).join('/') + '）⇒ 仅作待确认候选，不自动取得规则地位'],
+    }
+  }
+  return { kind: 'rule', confidence: 'medium', reasons: ['约束语汇 ' + words.slice(0, 3).join('/')] }
+}
+
+/**
+ * 从记忆文本里抽出规则层（分项，供注入侧分层措辞与"不参与裁剪"）。
+ *
+ * @param {object} input
+ * @param {string} [input.userText] 用户级记忆（跨工作区恒定；**规则真源**，见文件头）
+ * @param {string} [input.notesText] 工作区级项目笔记（第二层）
+ * @param {string} [input.rulesLayeringMode] 'off' | 'self' | 'none'
+ *   - `'off'`：**默认**。返回空规则层（调用方回落旧行为：统一措辞 + 原有节奏）。这就是"新旧并存 + 开关回退"。
+ *   - `'self'`：只看**当前 agent 自己写的** user 层（隔离子代理/外部导入的规则，防串线）。
+ *   - `'none'`：不看任何 user 层（只保留工作区级）。
+ * @param {string} [input.ownerSessionId] `rulesLayeringMode='self'` 时用于判定"是不是我自己写的"
+ * @returns {{version:string, mode:string, enabled:boolean, text:string, rules:Array, candidates:Array,
+ *            references:Array, counts:object, chars:{rules:number,candidates:number,total:number}}}
+ */
+export function extractRulesLayerPre(input = {}) {
+  const o = input && typeof input === 'object' ? input : {}
+  const mode = clampMode(o.rulesLayeringMode)
+  const empty = {
+    version: RULES_LAYER_VERSION, mode, enabled: false, text: '', rules: [], candidates: [], references: [],
+    counts: { entries: 0, rules: 0, candidates: 0, references: 0 }, chars: { rules: 0, candidates: 0, total: 0 },
+  }
+  if (mode === null) return empty
+
+  const sources = []
+  const pushAll = (layer, text) => {
+    for (const e of splitMemoryEntriesPre(text)) sources.push({ layer, ...e })
+  }
+  // 模式语义（与文件头一致，别写反）：
+  //   'self'  ⇒ 看用户级（跨工作区恒定）+ 工作区级
+  //   'none'  ⇒ **不看任何用户级**，只看工作区级（用于"工作区规则覆盖用户规则"的场景）
+  if (mode !== 'none') pushAll('user', o.userText)
+  pushAll('project', o.notesText)
+
+  const rules = []
+  const candidates = []
+  const references = []
+  for (const e of sources) {
+    const c = classifyText(e.text)
+    const rec = { layer: e.layer, id: e.id, anchorLine: e.anchorLine, kind: c.kind, confidence: c.confidence, reasons: c.reasons, text: e.text }
+    if (c.kind === 'rule') rules.push(rec)
+    else if (c.kind === 'candidate') candidates.push(rec)
+    else references.push(rec)
+  }
+
+  // 规则层文本：只含规则条目（高/中置信），逐条一行摘要，**不掺参考类**
+  const renderLine = (r) => '- ' + ruleSummaryPre(r.text)
+  const parts = []
+  if (rules.length) parts.push(rules.map(renderLine).join('\n'))
+  const text = parts.join('\n')
+  return {
+    version: RULES_LAYER_VERSION, mode, enabled: true, text, rules, candidates, references,
+    counts: { entries: sources.length, rules: rules.length, candidates: candidates.length, references: references.length },
+    chars: { rules: text.length, candidates: candidates.reduce((a, r) => a + ruleSummaryPre(r.text).length + 2, 0), total: text.length },
+  }
+}
+
+/** 模式解析：`null` 表示"未启用"（调用方沿用旧行为）。 */
+function clampMode(v) {
+  const s = clean(v).trim().toLowerCase()
+  if (!s || s === 'off' || s === 'false' || s === '0') return null
+  if (s === 'self' || s === 'none' || s === 'all') return s
+  return null // 非法值一律当"未启用"（fail-soft，不因配置写错而改变注入）
+}
+
+/** 取第一条非空行并裁剪（规则条目往往首行就是规则名，够用且省 token）。 */
+export function firstLine(text, max = 200) {
+  const lines = clean(text).split('\n').map((l) => l.trim()).filter(Boolean)
+  const first = lines[0] || ''
+  return first.length > max ? first.slice(0, Math.max(1, max - 1)) + '…' : first
+}
+
+/**
+ * 规则条目的**摘要行**（渲染用）：跳过日期小节标题（`## 2026-08-14`）与纯标点行，
+ * 取第一条实质内容。
+ *
+ * **为什么需要它**（实测踩坑）：既有记忆文件的条目结构是「锚点 → `## 日期` → 正文」，
+ * 直接用 `firstLine` 会渲染成 `- ## 2026-08-14` —— 规则内容全丢，只剩日期，
+ * 而且**看起来还挺正常**（这条断言首跑就红在"连续 6 轮规则都在"上，因为摘要里没有规则文本）。
+ *
+ * ★P6B：`[kind:x]` 行内标记在此**剥离**（标记只服务盘上审计与分类持久化，
+ * 注入摘要保持干净）；时间戳 `HH:MM` 一并剥离（对规则语义是噪声）。
+ */
+export function ruleSummaryPre(text, max = 200) {
+  const lines = clean(text).split('\n').map((l) => l.trim()).filter(Boolean)
+  for (const l of lines) {
+    if (DATE_SECTION_RE.test(l)) continue
+    if (/^<!--/.test(l)) continue
+    if (/^[-*+]\s*$/.test(l)) continue
+    // 去掉列表前缀再返回，保持一条一行
+    let body = l.replace(/^[-*+]\s+/, '')
+    // ★P6B：剥行内 kind 标记与前置时间戳（只影响渲染，不回写盘上原文）
+    body = body.replace(LOG_KIND_TAG_RE_V1, ' ').trim()
+    body = body.replace(/^\d{1,2}:\d{2}\s+/, '').trim()
+    return body.length > max ? body.slice(0, Math.max(1, max - 1)) + '…' : body
+  }
+  return ''
+}
+
+/**
+ * 规则段渲染（**供注入侧直接使用**）：标题 + 引导语 + 逐条规则。
+ *
+ * 措辞分层的关键（T7-3）：**规则类用约束语**（"必须遵守"），**参考类保留"参考"语义**。
+ * 两段引导语必须**不相同** —— 断言直接锁这一点，防止有人改回统一措辞。
+ *
+ * @param {object} rules `extractRulesLayerPre` 的返回值
+ * @param {object} [opts]
+ * @param {string} [opts.title] 段标题（默认常量）
+ * @param {string} [opts.guide] 引导语（默认常量）
+ * @returns {{text:string, chars:number, guide:string}}
+ */
+export function renderRulesSectionPre(rules, opts = {}) {
+  const r = rules && typeof rules === 'object' ? rules : {}
+  const list = Array.isArray(r.rules) ? r.rules : []
+  if (!list.length) return { text: '', chars: 0, guide: '' }
+  const title = clean((opts && opts.title) || RULES_SECTION_TITLE_V1)
+  const guide = clean((opts && opts.guide) || RULES_SECTION_GUIDE_V1)
+  const text = '\n' + title + '\n' + guide + '\n' + list.map((x) => '- ' + ruleSummaryPre(x.text)).join('\n')
+  return { text, chars: text.length, guide }
+}
+
+/**
+ * 规则段标题（T7-3：与参考段的措辞**必须不同**；断言直接比对两者）。
+ * 用户可通过 `promptLayerOverrides.snapshotRulesTitle` 覆盖。
+ */
+export const RULES_SECTION_TITLE_V1 = '[规则 — 用户级硬性约束 · 必须遵守]'
+
+/**
+ * 规则段引导语：**约束语**（"以下为必须遵守的约束"），不是"只是参考"。
+ * 这句话就是 P6A「措辞」要修的病：旧开场白把规矩与资料统一降格为「只是背景事实与规则参考」。
+ */
+export const RULES_SECTION_GUIDE_V1 = '以下条目是用户明确要求长期遵守的约束，不是可选背景。凡与其它内容冲突，以本节为准；无法满足时必须显式说明。'
+
+/** 参考段引导语（保留"参考"语义，与规则段措辞不同）。 */
+export const REFERENCE_SECTION_GUIDE_V1 = '以下为背景资料与历史记录，供参考与检索定位；与上面的规则冲突时不适用。'

package/lib/semantic-js.js

@@ -342,6 +342,21 @@ export function createJsSemanticEnginePre(opts = {}) {
         return null // fail closed:词法回退由调用方自然发生
       }
     },
+    /**
+     * 2026-09-14（三层契约 C3）：暴露**批量段落嵌入**通道 —— L0 向量索引接线
+     * （`lib/l0-index-sync.js`）需要把 L0 摘要本身变成向量，而 rank() 只返回
+     * 「查询 vs 内部缓存索引」的余弦分，**不产出向量**（此前宿主没有任何拿向量的口子，
+     * 这是 `createL0IndexPre` 一直零引用、无法接线的原因之一）。
+     *
+     * 语义：裸文本数组 → `Float32Array[]`（e5 口径为 384 维已归一化；前缀 `passage: ` 由引擎内部加，
+     * 与 rank 的 `query: ` 前缀对称，调用方传**裸文本**）。
+     * 失败语义：模型资产缺失/加载失败 → 抛错（**不吞**）—— 由调用方 fail-soft（索引侧只 diag 一行，
+     * 不阻塞任何检索路径）。本方法不改任何内部状态（不缓存、不动 idx），纯计算。
+     */
+    async embedPassages(texts) {
+      const t = await ensureTier()
+      return t.embedPassages(Array.isArray(texts) ? texts : [])
+    },
     _resetForTest() { tier = null; tierPromise = null; degraded = ''; idx = { miv: null, entries: [] }; rebuilding = null },
   }
 }

package/lib/shadow-retrieval.js

@@ -402,14 +402,14 @@ const MEMORY_ID_STRICT = /^mem_[0-9a-f]{32}$/
 
 /** §11 retrievalId(确定性,可重放;非长期内容身份)。 */
 export function buildRetrievalId(sessionId, contextVersion, triggerSegmentId, memoryIndexVersion) {
-  const sessionIdHash = first32(sha256Str('retrieval-pre-v1\u0000' + sessionId))
-  const parts = ['retrieval-pre-v1', sessionIdHash, contextVersion, triggerSegmentId, memoryIndexVersion, GATE_POLICY_VERSION, LEXICAL_POLICY_VERSION]
+  const sessionIdHash = first32(sha256Str('retrieval-v1\u0000' + sessionId))
+  const parts = ['retrieval-v1', sessionIdHash, contextVersion, triggerSegmentId, memoryIndexVersion, GATE_POLICY_VERSION, LEXICAL_POLICY_VERSION]
   return RETRIEVAL_PREFIX + first32(sha256Str(JSON.stringify(parts)))
 }
 
 /** §11 candidateId:同 memoryId 内容变化后 candidateId 因版本/digest 改变。 */
 export function buildCandidateId(retrievalId, memoryId, sourceEpoch, sourceVersion, recordDigest) {
-  const parts = ['candidate-pre-v1', retrievalId, memoryId, sourceEpoch, sourceVersion, recordDigest]
+  const parts = ['candidate-v1', retrievalId, memoryId, sourceEpoch, sourceVersion, recordDigest]
   return CANDIDATE_PREFIX + first32(sha256Str(JSON.stringify(parts)))
 }