@modusensus/dsh-mneme 0.9.1 → 0.9.2

package/src/scope-state.js

@@ -0,0 +1,277 @@
+// issue #471：政策轴（作用域级可逆闸门）。
+//
+// 与事实轴（src/scope.js 的 agent_scope / workspace_scope 标注）的分野：
+//   事实轴回答「这条记忆属于谁」——持久，跟着记忆行走（strictScope 那道可见性硬墙、
+//   scope_changes 那份人工修正审计都长在这条轴上）。
+//   政策轴回答「这个作用域现在通不通」——暂时，由人单方面按下、松开即恢复，存在运行
+//   期表 scope_state 里（建表注释见 src/store.js），不改任何记忆行、不改任何配置键、
+//   不重启。
+//
+// 为什么单独一个模块：判定要与存储能各自被检验。本模块不 import store.js——它只接
+// 收一个「读状态行」的函数，于是 test 可以直接构造暂停集合、不必开库（与
+// write-admission.js 把判据实现与存储解耦同款）。存储读写留在 store.js。
+//
+// 依赖方向是单向的：store.js import 本模块的三个 normalizeScopeState*（落库前把
+// 维度/值/状态归一到可解释的枚举），本模块 import scope.js 的 scopeKeyOf；scope.js
+// 不 import 任何本包模块，所以不成环。归一化与判定同处一个文件是刻意的——两者共享
+// 同一套枚举常量（SCOPE_STATE_DIMENSIONS / _VALUES / _ALL），分开写会让「写入侧认的
+// 值」与「判定侧认的值」有机会各自漂移，那正是本仓 gateByScope 注释里记着的坑。
+//
+// 为什么判定只写一份：src/service.js 的 gateByScope 注释已写明「过滤点漂移」是本仓
+// 真实踩过的坑——`entity:` 与 `attr:` 两条前缀路曾在入口就 return，整条绕过硬墙。
+// 政策轴照同一纪律办：判定收在本模块，service 侧只挂在既有出口上。
+//
+// 两级开关（与 src/write-admission.js:11 同口径）：
+//   enabled 打开时：被按下的作用域其候选照常注入，但留一条审计行说清「本应被拦下」；
+//   enforce 打开时：真的不注入。
+// 先看「如果按下会少掉多少」，再决定要不要真按——writeAdmission 与 preInjectGate
+// 都是这么分两次上线的。两个开关都默认关时本模块的判定恒为「通」，service 侧拿到的
+// 是原数组本身（不是等值副本），行为与改动前逐字段一致。
+import { scopeKeyOf } from "./scope.js";
+
+// 审计口径（llm_audit_logs 的既有列）：trigger_source = 组件名，operation_type =
+// 动作名，status='skipped' = 本行没有产生任何 LLM 花费（与 summarize 的间隔门、
+// 尖峰门、writeAdmission 同款读法）。
+export const SCOPE_STATE_TRIGGER_SOURCE = "scopeState";
+export const SCOPE_STATE_OPERATION_TYPE = "scope_state_gate";
+
+// 作用域维度。刻意只取本仓已有的两维，不照搬 dsh-domain-role 的四级作用域——它的
+// project 级存在一个已知缺口（其 docs/06-limitations.md 的 B1：「项目级暂停不读会话
+// 存档 ⇒ 判不出就不拦」），而本仓的 agent_scope / workspace_scope 都是确定值，不存在
+// 「判不出归属」的情况。
+export const SCOPE_STATE_DIMENSIONS = ["agent", "workspace"];
+
+// 状态两值。active 是「松开」，paused 是「按下」——写成显式两值而不是「有行=按下」，
+// 是为了让回执能如实报出「这一路现在是通的」，而不是让「没有行」同时承担「从未按过」
+// 与「按过又松开了」两种意思。
+export const SCOPE_STATE_VALUES = ["active", "paused"];
+
+// 该维度全局（不针对某个具体标签）。注意它只命中「在这一维上有标注」的记忆：未标注
+// 的行（scopeKeyOf 为 null）在该维度上不属于任何一路，全局按下也不该把它们卷进来
+// ——它们对谁都可见，不是「这一路」。
+export const SCOPE_STATE_ALL = "*";
+
+/**
+ * 维度归一化。脏输入返回 null 由调用方拒绝（写入侧）或忽略（读取侧）。
+ * @param {unknown} raw
+ * @returns {"agent"|"workspace"|null}
+ */
+export function normalizeScopeStateDimension(raw) {
+  return SCOPE_STATE_DIMENSIONS.includes(raw) ? raw : null;
+}
+
+/**
+ * 作用域值归一化。与 scopeKeyOf 同款口径（非空 trim 字符串），额外的只有 '*'
+ * 这个哨兵值。空白/非字符串落 null——不做 trim 后回退，因为「按下空字符串」不是
+ * 一个可解释的意图（不像 resolveWriteScope 那样有「取不到就放宽」的正当理由）。
+ * @param {unknown} raw
+ * @returns {string|null}
+ */
+export function normalizeScopeStateValue(raw) {
+  if (typeof raw !== "string") return null;
+  const s = raw.trim();
+  if (!s) return null;
+  return s === SCOPE_STATE_ALL ? SCOPE_STATE_ALL : s;
+}
+
+/**
+ * 状态归一化。
+ * @param {unknown} raw
+ * @returns {"active"|"paused"|null}
+ */
+export function normalizeScopeStateState(raw) {
+  return SCOPE_STATE_VALUES.includes(raw) ? raw : null;
+}
+
+// 共享的空索引。enabled 关或表为空时返回它，让调用方的 `index.any` 短路检查是
+// 一次属性读取而不是一次分配。
+export const EMPTY_PAUSED_INDEX = Object.freeze({
+  byDimension: Object.freeze({ agent: new Set(), workspace: new Set() }),
+  any: false
+});
+
+/**
+ * 把状态行编成查找索引。只收 state='paused' 的行——active 行是「松开」的留痕，
+ * 不参与判定（保留它们是为了回执能报「你上次是松开的」，不是为了拦东西）。
+ *
+ * 为什么只保留一个维度→值的集合而不保留行本身：判定只需要「这个值在不在集合里」，
+ * 行上的 note/decided_at 是给人回看用的，不是判定输入。多留一份会让索引与表之间
+ * 出现第二份需要同步的状态。
+ *
+ * @param {Array<{dimension?: string, scope_value?: string, state?: string}>} rows
+ * @returns {{byDimension: {agent: Set<string>, workspace: Set<string>}, any: boolean}}
+ */
+export function buildPausedIndex(rows) {
+  const byDimension = { agent: new Set(), workspace: new Set() };
+  let any = false;
+  for (const row of rows ?? []) {
+    if (!row || row.state !== "paused") continue;
+    const dimension = normalizeScopeStateDimension(row.dimension);
+    if (!dimension) continue;
+    const value = normalizeScopeStateValue(row.scope_value);
+    if (!value) continue;
+    byDimension[dimension].add(value);
+    any = true;
+  }
+  return any ? { byDimension, any } : EMPTY_PAUSED_INDEX;
+}
+
+/**
+ * 一行记忆命中了哪些暂停作用域。返回命中明细（而不是布尔）是为了审计行能说清
+ * 「是被哪一路拦下的」——只留一个布尔，日后回看只知道「少了」，不知道为什么少。
+ *
+ * 比较用 scopeKeyOf（与去重键、检索加权共用同一把钥匙）：未标注行在该维度上不
+ * 参与比较，于是「按下 workspace=X」不会波及未标注的全局记忆。
+ *
+ * @param {object} m 记忆行
+ * @param {{byDimension: object, any: boolean}} index
+ * @returns {Array<{dimension: string, scope_value: string}>}
+ */
+export function matchPausedScopes(m, index) {
+  if (!index || index.any !== true) return [];
+  const hits = [];
+  for (const dimension of SCOPE_STATE_DIMENSIONS) {
+    const paused = index.byDimension[dimension];
+    if (!paused || paused.size === 0) continue;
+    const label = scopeKeyOf(dimension === "agent" ? m?.agent_scope : m?.workspace_scope);
+    if (label === null) continue;
+    if (paused.has(label)) hits.push({ dimension, scope_value: label });
+    // 全局按下排在具体值之后：两者同时命中时，报具体值比报 '*' 更有信息量
+    // （'*' 是「所有这一维的行」，具体值才是「就是这一路」）。
+    else if (paused.has(SCOPE_STATE_ALL)) hits.push({ dimension, scope_value: SCOPE_STATE_ALL });
+  }
+  return hits;
+}
+
+/**
+ * 命中的暂停作用域去重（审计行的 metadata.paused）。
+ * @param {Array<object>} rows
+ * @param {{byDimension: object, any: boolean}} index
+ * @returns {Array<{dimension: string, scope_value: string}>}
+ */
+export function distinctPausedScopes(rows, index) {
+  const seen = new Map();
+  for (const m of rows ?? []) {
+    for (const hit of matchPausedScopes(m, index)) {
+      seen.set(`${hit.dimension}\u0000${hit.scope_value}`, hit);
+    }
+  }
+  return [...seen.values()];
+}
+
+/**
+ * 政策轴闸门。判定无状态（每次现读一次状态表），因为表恒小（行数 = 被人按过的
+ * 作用域个数，个位数），而缓存会引入一套失效协议——面板或另一个进程改了状态后，
+ * 缓存要能立刻知道，那需要 IPC 或轮询；用一次小表读换掉整类「缓存过期」缺陷。
+ *
+ * @param {object} deps
+ * @param {() => Array<object>} [deps.listStates] 读状态行（store.listScopeStates）
+ * @param {(entry: object) => void} [deps.saveAudit] 写审计行（store.saveLlmAudit）
+ * @param {object} [deps.config] 已解析配置（读 scopeState.enabled / scopeState.enforce）
+ * @param {object} [deps.logger]
+ */
+export function createScopeStateGate({ listStates, saveAudit, config, logger } = {}) {
+  let warned = false;
+  const warn = (msg) => {
+    if (warned) return;
+    warned = true;
+    try {
+      logger?.warn?.(msg);
+    } catch {
+      // logger 自身故障不能影响检索路径——闸门坏掉时宁可放行（fail-open），
+      // 与 scope.js「解析失败绝不阻塞写入」同一哲学：政策轴是加在读取侧的一道
+      // 便利闸门，不是安全边界（安全边界是 strictScope 那道事实轴硬墙）。
+    }
+  };
+
+  const enabled = () => config?.scopeState?.enabled === true;
+  const enforce = () => config?.scopeState?.enforce === true;
+
+  /**
+   * 当前暂停索引。开关关、读失败、表为空都返回同一个空索引——三种情况下判定
+   * 都是「通」，调用方不需要区分。
+   */
+  function index() {
+    if (!enabled()) return EMPTY_PAUSED_INDEX;
+    try {
+      return buildPausedIndex(typeof listStates === "function" ? listStates() : []);
+    } catch (e) {
+      warn(`[dsh-mneme] scope-state gate: state read failed, gate is inert this call (${e?.message ?? e})`);
+      return EMPTY_PAUSED_INDEX;
+    }
+  }
+
+  /**
+   * 检索侧的过滤出口。**只在 enforce 档动手**——enabled 单开时这一侧不过滤，
+   * 与注入侧同一条两级语义（观察档不拦任何东西）。
+   *
+   * 开关关、观察档、没有暂停行时返回**原数组本身**（不是等值副本）——「默认路径
+   * 零行为变化」这条验收要靠引用相等来钉死，副本会让它退化成「内容看起来一样」。
+   *
+   * 这一侧不写审计行：审计的口径是「本应被拦下的注入候选有多少」，只有注入路径
+   * 才知道这件事。检索是工具与面板主动问的，把每次问答都记一行只会让审计表按
+   * 查询频次增长，而查到的读数并不回答「按下会少掉多少」。
+   */
+  function filter(rows) {
+    const idx = index();
+    if (!idx.any || !enforce() || !Array.isArray(rows) || rows.length === 0) return rows;
+    return rows.filter((m) => matchPausedScopes(m, idx).length === 0);
+  }
+
+  /**
+   * 注入面的闸门。返回过滤后的候选与「本应被拦下」的明细。
+   *
+   * enforce 关（观察档）时**不过滤**，但留一条审计行——这正是两级开关的意义：
+   * 先在真实流量里看「如果按下会少掉多少」，再决定要不要真按。审计写失败只 warn
+   * （同 saveLlmAudit 的调用惯例），注入本身照常完成。
+   *
+   * @param {Array<object>} rows 注入候选（图召回合并之后、pin 池之前）
+   * @returns {{rows: Array<object>, gated: Array<object>, enforced: boolean}}
+   */
+  function gateInjection(rows) {
+    const idx = index();
+    if (!idx.any || !Array.isArray(rows) || rows.length === 0) {
+      return { rows, gated: [], enforced: false };
+    }
+    const gated = rows.filter((m) => matchPausedScopes(m, idx).length > 0);
+    if (gated.length === 0) return { rows, gated: [], enforced: false };
+    const enforced = enforce();
+    record(idx, gated, enforced);
+    return {
+      rows: enforced ? rows.filter((m) => matchPausedScopes(m, idx).length === 0) : rows,
+      gated,
+      enforced
+    };
+  }
+
+  function record(idx, gated, enforced) {
+    if (typeof saveAudit !== "function") return;
+    // llmAudit 关时一行都不写：那个开关同时关掉审计行的启动期清理
+    // （index.js 的 deleteOldLlmAudits），在无保留期的表里按调用频次增长是不对的
+    // （与 write-admission.js 的同一条理由）。
+    if (config?.llmAudit?.enabled === false) return;
+    try {
+      saveAudit({
+        trigger_source: SCOPE_STATE_TRIGGER_SOURCE,
+        operation_type: SCOPE_STATE_OPERATION_TYPE,
+        // 不是模型调用，但该列 NOT NULL——用显式占位串，免得被当成某条路由的
+        // 花费来源统计进去（同 write-admission.js）。
+        model_id: "-",
+        status: "skipped",
+        related_memory_ids: gated.map((m) => m?.id).filter(Boolean),
+        metadata: {
+          gate: "scopeState",
+          paused: distinctPausedScopes(gated, idx),
+          gated: gated.length,
+          // enforced 由开关推出而不是另存一个入参：两者各存一份就会出现
+          // 「闸门动手了但行上写着 false」这种自相矛盾的记录。
+          enforced
+        }
+      });
+    } catch (e) {
+      warn(`[dsh-mneme] scope-state audit write failed (never blocks injection): ${e?.message ?? e}`);
+    }
+  }
+
+  return { enabled, enforce, index, filter, gateInjection };
+}

package/src/service.js

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { TYPE_FILE, MIRROR_READONLY_TYPES } from "./mirror.js";
 import { updatedAtBounds } from "./store.js";
 import { normalizeExplicitScope, scopeKeyOf } from "./scope.js";
+import { createScopeStateGate } from "./scope-state.js";
 import { STR, langOf } from "./lang.js";
 import { computeHeat } from "./heat.js";
 import { recallStats } from "./recall-stats.js";
@@ -185,6 +186,17 @@ export function computeRetrievalMetrics(actualIds, expectedIds) {
 
 export function createService({ store, mirror, config, onWrite, logger, documentIndex, writeAdmission }) {
   const language = langOf(config);
+
+  // issue #471 政策轴：作用域级可逆闸门。判定实现住 src/scope-state.js（与存储解耦，
+  // test 可以直接构造暂停集合、不必开库）；这里只把 store 的读写函数接上去。
+  // 每次调用现读一次状态表，不做缓存：表恒小（行数 = 被人按过的作用域个数），
+  // 而缓存要配一套失效协议才能让面板/另一进程的改动立刻可见（见 scope-state.js）。
+  const scopeStateGate = createScopeStateGate({
+    listStates: () => store.listScopeStates(),
+    saveAudit: (entry) => store.saveLlmAudit(entry),
+    config,
+    logger
+  });
   // Optional dream scheduler hook, installed via setDreamHook after creation
   // (the scheduler holds a reference back to the service, so it cannot be
   // passed in the constructor). Fired on the same write events as onWrite.
@@ -294,7 +306,11 @@ export function createService({ store, mirror, config, onWrite, logger, document
 
   function scheduleEmbed(memory) {
     try {
-      if (txDepth > 0) return; // deferred to the transaction's commit
+      // distill-tx-embed-gap: 入队而不是丢弃，transaction() 提交后补跑（#372 同款）。
+      if (txDepth > 0) {
+        pendingEmbed.push(memory);
+        return;
+      }
       if (!embedder || !memory?.id) return;
 
       // Readiness gate: embedder exposes `ready` (async init) and is not ready
@@ -346,6 +362,14 @@ export function createService({ store, mirror, config, onWrite, logger, document
   // 写入批量决定。回滚时由 transaction() 截断到事务前的基线（见 ROLLBACK 路径）。
   const pendingEntity = [];
 
+  // distill-tx-embed-gap：scheduleEmbed 在事务内曾被首行 `if (txDepth > 0) return;`
+  // 直接丢弃（注释写 deferred，transaction() 从不补跑）——与 #372 的实体抽取是
+  // 同一个 bug 模板，只是受害者换成了嵌入：自动蒸馏的 session:* 行因此 100%
+  // 拿不到向量。照 #372 先例入队，事务提交后补跑；回滚时截断回本层基线，
+  // 绝不给已回滚的行嵌向量。队列同样不设上限：元素只是对已落库行的引用，
+  // cap 丢最旧等于把「向量被静默丢弃」换个量级带回来。
+  const pendingEmbed = [];
+
   function scheduleEntityExtraction(memory) {
     if (txDepth > 0) {
       pendingEntity.push(memory);
@@ -393,10 +417,27 @@ export function createService({ store, mirror, config, onWrite, logger, document
    * activeStoreSize 的理由：两处各写一份过滤条件，漂移只在某条路径上显形）。
    *
    * strictScope 关（默认）或 scope 解析不到时原样返回：行为与改动前逐字节一致。
+   *
+   * issue #471 政策轴接在这里：判定收在 scope-state.js（同一个「过滤点不许漂移」
+   * 的理由），本函数只按顺序挂上去。政策轴排在事实轴**前面**——它更便宜（一次小
+   * 表读，无逐行字段比较），且语义上「这一路现在通不通」先于「你看不看得见」。
+   *
+   * 注意政策轴的短路条件与事实轴不同：它不看 `scope`。事实轴要有 scope 才知道
+   * 「以谁的眼睛看」，而政策轴问的是「这条路还开着吗」，与调用方是谁无关——会话
+   * 身份解析失败不该让闸门整条失效（故政策轴在 scope 为 null 时照样生效）。
+   *
+   * **覆盖面只到「喂给模型的那几条路」**：融合池 + `entity:`/`attr:` 前缀路 +
+   * 注入候选池，以及 dream/sleep 的整理读入口。`memory_list` / `memory_get` /
+   * 面板列表**刻意不过这道闸**（它们走 `strictVisibility` 与 store.list 的
+   * `visibility` 参数，与 `gateByScope` 平行的另一条链）。理由：按下之后人还要能
+   * 查「我到底按下了什么、里面有什么」，那是检视面不是供料面；把检视面也关掉，
+   * 人就没有任何入口找回被暂停的行、也没法确认该不该松开。这也是为什么按下的是
+   * 政策而不是事实：行还在，只是不再喂给模型。
    */
   function gateByScope(rows, scope) {
-    if (config?.strictScope !== true || !scope) return rows;
-    return rows.filter((m) => isVisibleInScope(m, scope));
+    const gated = scopeStateGate.filter(rows);
+    if (config?.strictScope !== true || !scope) return gated;
+    return gated.filter((m) => isVisibleInScope(m, scope));
   }
 
   /**
@@ -1152,6 +1193,8 @@ export function createService({ store, mirror, config, onWrite, logger, document
     // #372: 记住本层事务开始时的队列深度——回滚时截断回这里。本层（及更深的
     // 嵌套层）入队的抽取随回滚一并丢弃，外层已提交未 drain 的条目不受牵连。
     const baseline = pendingEntity.length;
+    // distill-tx-embed-gap: 嵌入队列用同一套基线机制，与实体抽取保持一致。
+    const embedBaseline = pendingEmbed.length;
     let committed = false;
     try {
       const result = fn();
@@ -1164,6 +1207,8 @@ export function createService({ store, mirror, config, onWrite, logger, document
       // 复审抓出：仅靠 committed 门挡 drain 时，回滚条目会滞留队列、被下一个
       // 成功事务误抽）。外层未提交的条目在 baseline 之前，原样保留。
       pendingEntity.length = baseline;
+      // distill-tx-embed-gap: 同理，绝不给已回滚的行嵌向量。
+      pendingEmbed.length = embedBaseline;
       throw error;
     } finally {
       txDepth--;
@@ -1180,6 +1225,10 @@ export function createService({ store, mirror, config, onWrite, logger, document
       // （txDepth 仍 >0 时 schedule 会重新入队，与 drain 形成自旋）——条目等最外层
       // COMMIT 后统一补跑。
       if (committed && txDepth === 0) drainPendingEntityExtraction();
+      // distill-tx-embed-gap: 补跑事务内排队的嵌入——同一套嵌套规则：内层提交
+      // 不 drain（txDepth 仍 >0 时 scheduleEmbed 会重新入队），等最外层 COMMIT
+      // 后统一补跑。放在 drainPendingEntityExtraction 之后无依赖，仅保持顺序。
+      if (committed && txDepth === 0) drainPendingEmbeds();
     }
   }
 
@@ -1189,6 +1238,14 @@ export function createService({ store, mirror, config, onWrite, logger, document
     }
   }
 
+  // distill-tx-embed-gap: drain 与 pendingEntity 同构。补跑走 scheduleEmbed 本体，
+  // 因此 embedder 未 ready / 无 schedule 接口等既有分流逻辑全部复用，不另写一路。
+  function drainPendingEmbeds() {
+    while (pendingEmbed.length) {
+      scheduleEmbed(pendingEmbed.shift());
+    }
+  }
+
   /**
    * Embed an arbitrary query text and return its vector (null on failure / no
    * embedder). Used by the injector to prefetch the semantic-first recall
@@ -1753,6 +1810,11 @@ export function createService({ store, mirror, config, onWrite, logger, document
     if (config?.strictScope === true && scope) {
       candidates = candidates.filter((m) => isVisibleInScope(m, scope));
     }
+    // issue #471 政策轴：挂在事实轴之后、pin 池之前。位置与上面同一条纪律——必须在
+    // 图召回合并之后，否则出局行会被 entityRecall 打上 graphHint 带回候选池。
+    // 观察档（enabled 开、enforce 关）在这里留一条审计行说清「本应被拦下几条」，
+    // 但不改 candidates；拦截档才真的摘掉。审计写失败只 warn，注入照常完成。
+    candidates = scopeStateGate.gateInjection(candidates).rows;
     // #249 第一批：B1 pin 池。取在相关性排序之后、轮换之前——取谁按此刻的候选
     // 次序（即相关性次序），取到后从候选中摘除，于是下面的轮换重排碰不到它们
     // （验收：pin 不参与跨轮轮换）。独立预算的两层意义：pin 既不占 maxItems
@@ -2516,6 +2578,16 @@ export function createService({ store, mirror, config, onWrite, logger, document
     mergeHumanEdits,
     toApiList,
     isVisibleInScope,
+    // issue #471 政策轴：按下/松开与读取照 store 那三条件透传（纯 bookkeeping，
+    // 不挂 write hook——它们不动任何记忆行，同 saveConflictPending 那批）。
+    setScopeState: (r) => store.setScopeState(r),
+    getScopeState: (d, v) => store.getScopeState(d, v),
+    listScopeStates: (o) => store.listScopeStates(o),
+    // 巩固（dream.js）侧的过滤出口。暴露出来而不是让 dream 自己读状态表，是因为
+    // 判定只能有一份实现（gateByScope 注释里那条「过滤点漂移」的教训）；dream 侧
+    // 的三个读入口各自的附加条件不同（有的排 forgotten、有的不排），但「被按下的
+    // 作用域不参与巩固」这一层对三处是一样的。enforce 关时本函数原样返回入参。
+    filterPaused: (rows) => scopeStateGate.filter(rows),
     transaction,
     getDistillCursor: (sessionId) => store.getDistillCursor(sessionId),
     setDistillCursor: (sessionId, lastSeq) => store.setDistillCursor(sessionId, lastSeq),
@@ -2592,6 +2664,11 @@ export function createService({ store, mirror, config, onWrite, logger, document
     search: (q, o) => store.search(q, o),
     searchVector: (v, o) => store.searchVector(v, o),
     embeddedCount: () => store.embeddedCount(),
+    // 向量出身的两个分组读数：状态端点 /semantic 用它们区分「有向量」和
+    // 「可检索」（byModel 按行级 embedding_model，byDimension 按向量维数）。
+    // passthrough 形状与 embeddedCount 同款，api 层不直接摸 store。
+    embeddingModelBreakdown: () => store.embeddingModelBreakdown(),
+    embeddingDimensionBreakdown: () => store.embeddingDimensionBreakdown(),
     list: (o) => store.list(o),
     all: () => store.all(),
     count: (type, opts) => store.count(type, opts),

package/src/settings.js

@@ -174,6 +174,13 @@ const FEATURE_FLAG_BOOLEANS = [
   // Issue #17（v0.8.0 A3）：strictScope 硬过滤——他 scope 完全不可见（关闭时
   // 为 A2 软隔离：降权保留可见）。
   "strictScope",
+  // Issue #471：政策轴——作用域级可逆闸门（scopeState）。与上面两个键是两条不同的
+  // 轴：那两个管「这条记忆属于谁」（事实轴），这两个管「这个作用域现在通不通」
+  // （政策轴，按作用域整体按下、跨会话存续、松开即恢复）。两级语义同
+  // writeAdmission/preInjectGate——enabled 跑判定（观察档，留审计行但照常注入）、
+  // enforce 真拦（不注入）；都默认关。点号键平铺存、合并时展开回 scopeState 对象。
+  "scopeState.enabled",
+  "scopeState.enforce",
   // 工具暴露开关（v0.8.5）：记忆已每轮自动注入，memory_search/memory_archive
   // 在慢/轻量模型上是多余往返，面板可关（默认关=行为不变）。
   "disableMemorySearch",

package/src/store.js

@@ -2,6 +2,15 @@ import { DatabaseSync } from "node:sqlite";
 import { randomUUID } from "node:crypto";
 import { statSync } from "node:fs";
 import { contentHashOf } from "./content-hash.js";
+// 政策轴（issue #471）的归一化函数。刻意只取归一化，不取判定：判定（buildPausedIndex /
+// matchPausedScopes / createScopeStateGate）留在 scope-state.js，由 service 侧消费，
+// 存储层只管「一格状态怎么落」。依赖方向 store → scope-state → scope 是单向的
+// （scope.js 不 import 任何本包模块），所以不构成环。
+import {
+  normalizeScopeStateDimension,
+  normalizeScopeStateState,
+  normalizeScopeStateValue
+} from "./scope-state.js";
 
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS memories (
@@ -185,6 +194,25 @@ CREATE TABLE IF NOT EXISTS scope_changes (
 );
 CREATE INDEX IF NOT EXISTS idx_scope_changes_memory ON scope_changes(memory_id);
 
+-- scope_state: v0.9.1 政策轴（issue #471）。与 scope_changes 那条事实轴相对：
+-- scope_changes 记「某条记忆的归属被人工改过」（跟着记忆走），本表记「某个作用域
+-- 现在通不通」（跟着作用域走）。按下/松开都是单方面动作，不触碰任何记忆行，
+-- 松开即恢复——所以它是可逆的，而逐条 forget/archive 不是。
+-- dimension 只认 'agent'|'workspace'（scopeKeyOf 那两个维度）；scope_value='*'
+-- 表示该维度全局。一行一格，重复按下同一状态不刷新 decided_at（见 setScopeState）。
+-- Bookkeeping like the other audit tables: it never triggers write hooks.
+CREATE TABLE IF NOT EXISTS scope_state (
+  id           TEXT PRIMARY KEY,
+  dimension    TEXT NOT NULL,
+  scope_value  TEXT NOT NULL,
+  state        TEXT NOT NULL,               -- active | paused
+  note         TEXT,
+  decided_at   TEXT NOT NULL
+);
+-- 唯一性靠独立索引（本仓惯例：UNIQUE 不进 CREATE TABLE，见 idx_memory_provenance_link）。
+-- 它同时是 setScopeState 那条 UPSERT 的冲突目标，所以不能省。
+CREATE UNIQUE INDEX IF NOT EXISTS idx_scope_state_key ON scope_state(dimension, scope_value);
+
 -- llm_audit_logs: every background LLM call (autoDream consolidation + summary,
 -- autoSummarize compression) is recorded here — tokens in/out, duration, status
 -- and the trigger that caused it (Bug8). Failures are captured as status='error'
@@ -604,6 +632,20 @@ function toScopeChange(row) {
   };
 }
 
+// scope_state 行 → 读侧对象（issue #471）。NULL note 落 undefined，与
+// toScopeChange 同口径。
+function toScopeState(row) {
+  if (!row) return undefined;
+  return {
+    id: row.id,
+    dimension: row.dimension,
+    scope_value: row.scope_value,
+    state: row.state,
+    note: row.note ?? undefined,
+    decided_at: row.decided_at
+  };
+}
+
 function toRecallRun(row) {
   if (!row) return undefined;
   return {
@@ -1733,6 +1775,32 @@ export function createStore(path) {
     ).all();
   }
 
+  /**
+   * Per-dimension counts over active embedded rows ('' = vector that failed to
+   * parse as an array — legacy garbage rows, not a real dimension).
+   *
+   * Why per-dimension: embeddedCount() alone says "has a vector", but vectors
+   * written by a different model/dimension are not comparable with the current
+   * query embedding — searchVector skips them, so they are "present" without
+   * being "retrievable". The status card needs this split to stop reporting a
+   * coverage number that silently counts unsearchable rows.
+   */
+  function embeddingDimensionBreakdown() {
+    return db.prepare(
+      `SELECT id, embedding FROM memories
+        WHERE embedding IS NOT NULL AND embedding != ''
+          AND forgotten = 0 AND archived = 0`
+    ).all().reduce((acc, row) => {
+      let dim = "";
+      try {
+        const parsed = JSON.parse(row.embedding);
+        dim = Array.isArray(parsed) ? String(parsed.length) : "";
+      } catch { /* unparseable vector counts under "" */ }
+      acc.set(dim, (acc.get(dim) ?? 0) + 1);
+      return acc;
+    }, new Map());
+  }
+
   function search(query, { limit = 20, includeArchived = false } = {}) {
     const q = String(query).trim();
     if (!q) return [];
@@ -1789,6 +1857,11 @@ export function createStore(path) {
     for (const row of rows) {
       const v = getParsedEmbedding(row.id);
       if (!v) continue;
+      // distill-tx-embed-gap 顺带修：维度不匹配的行按维度分流，直接跳过。旧路径
+      // 喂进 cosine 不等长就 return 0，换了模型/维度的旧向量以 0 分混进结果尾部
+      // （threshold 默认 0 时照样入选），检索方拿到的分数是跨向量空间的假值。
+      // 不等长的向量对本次查询没有可比分数，跳过是唯一诚实的处置。
+      if (v.length !== vector.length) continue;
       const score = cosine(vector, v);
       if (score >= threshold) scored.push({ row: { id: row.id }, score });
     }
@@ -2609,6 +2682,66 @@ export function createStore(path) {
     return rows.map(toScopeChange);
   }
 
+  /**
+   * 政策轴（issue #471）：按下或松开一个作用域。一行一格，靠
+   * idx_scope_state_key(dimension, scope_value) 做 UPSERT——重复按下同一状态
+   * 不刷新 decided_at（CASE WHEN），因为「第一次按下的时刻」才是回执该报的东西；
+   * 状态翻转则刷新，那是一次真的决策。
+   *
+   * note 的取舍与 decided_at 相反：非空的新 note 总是覆盖旧的，空的则原样留着。
+   * 理由是这条记录里「当前通不通」由 state 那一列承担，note 是**理由**——理由被
+   * 一次不带理由的重按抹掉是净损失（用户回看时只会看到「按下过」却不知道为什么），
+   * 而「清空理由」不是一个真实需求（要改就再按一次带上新理由）。这与本仓防御段
+   * 「宁可留着也不要静默丢」的取向一致。
+   *
+   * 归一化失败（维度/值/状态任一非法）返回 undefined，由调用方拒绝——本表只存
+   * 可解释的三种枚举，与 memories 的 scope 列不同：那里脏输入落 NULL 是正当的
+   * （「未标注」本身有语义），这里落 NULL 没有任何意思，会静默变成一行永远不
+   * 生效的状态。
+   */
+  function setScopeState({ dimension, scope_value, state, note, decided_at }) {
+    const dim = normalizeScopeStateDimension(dimension);
+    const val = normalizeScopeStateValue(scope_value);
+    const st = normalizeScopeStateState(state);
+    if (!dim || !val || !st) return undefined;
+    const at = normalizeOccurredAt(decided_at) ?? nowIso();
+    const noteText = normalizeScopeText(note);
+    db.prepare(
+      `INSERT INTO scope_state (id, dimension, scope_value, state, note, decided_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(dimension, scope_value) DO UPDATE SET
+         state = excluded.state,
+         note = COALESCE(excluded.note, scope_state.note),
+         decided_at = CASE WHEN scope_state.state = excluded.state THEN scope_state.decided_at ELSE excluded.decided_at END`
+    ).run(randomUUID(), dim, val, st, noteText, at);
+    return toScopeState(
+      db.prepare("SELECT * FROM scope_state WHERE dimension = ? AND scope_value = ?").get(dim, val)
+    );
+  }
+
+  /** 政策轴状态行（单格）。 */
+  function getScopeState(dimension, scope_value) {
+    const dim = normalizeScopeStateDimension(dimension);
+    const val = normalizeScopeStateValue(scope_value);
+    if (!dim || !val) return undefined;
+    return toScopeState(
+      db.prepare("SELECT * FROM scope_state WHERE dimension = ? AND scope_value = ?").get(dim, val)
+    );
+  }
+
+  /**
+   * 政策轴状态行（全量）。不提供按维度/值过滤的参数——闸门判定要的就是全量
+   * （一次现读一次索引），过滤留到 scope-state.js 的 buildPausedIndex 里做。
+   * 排 decided_at DESC + rowid DESC 同 listScopeChanges（毫秒精度同毫秒写入
+   * 时 UUID 排序随机，回执要报「最近一次决策」就得有确定的次键）。
+   */
+  function listScopeStates({ state } = {}) {
+    const rows = state
+      ? db.prepare("SELECT * FROM scope_state WHERE state = ? ORDER BY decided_at DESC, rowid DESC").all(state)
+      : db.prepare("SELECT * FROM scope_state ORDER BY decided_at DESC, rowid DESC").all();
+    return rows.map(toScopeState);
+  }
+
   function getFailureStats({ since } = {}) {
     const clause = since ? "WHERE created_at >= ?" : "";
     const params = since ? [since] : [];
@@ -3233,6 +3366,7 @@ export function createStore(path) {
     needsEmbeddingFor,
     hasStaleEmbedding,
     embeddingModelBreakdown,
+    embeddingDimensionBreakdown,
     searchVector,
     saveDreamRun,
     lastDreamRunAt,
@@ -3281,6 +3415,11 @@ export function createStore(path) {
     countConflictPending,
     saveScopeChange,
     listScopeChanges,
+    // 政策轴（issue #471）：按下/松开一个作用域。纯 bookkeeping，不调
+    // incrementGeneration()——它不动任何记忆行，动它只会让所有缓存无谓失效。
+    setScopeState,
+    getScopeState,
+    listScopeStates,
     createEntity,
     findEntityByName,
     findEntityById,