@modusensus/dsh-mneme 0.9.1 → 0.9.3

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/scope.js

@@ -14,6 +14,28 @@
 // 只关「自动标注」，不能连读取身份一起关，否则 strictScope 硬墙被静默拆掉
 // （fail-open）。
 
+/**
+ * 免 inject 读取一个可选服务。cordis 4 的 ctx 是 Proxy，裸读未在 inject 声明的
+ * 属性会抛 "cannot get property ... without inject"（不是返回 undefined），所以
+ * 有 reflect 时优先走 ctx.reflect.get；旧宿主没有 reflect、ctx 是普通对象，裸读
+ * 此时安全——与 api.js:205 / index.js:583 的 webServer 同一形状。
+ *
+ * 服务缺失是合法状态（headless / 旧宿主 / 服务未激活），返回 undefined 让调用方
+ * 走既有降级路径，不告警：这不是故障。
+ * @param {object} ctx
+ * @param {string} name
+ * @returns {*}
+ */
+function readOptionalService(ctx, name) {
+  try {
+    if (typeof ctx?.reflect?.get === "function") return ctx.reflect.get(name);
+    return ctx?.[name];
+  } catch {
+    // 无 reflect 却又是 Proxy（或 accessor 自身抛错）：按「未提供」处理。
+    return undefined;
+  }
+}
+
 /**
  * @param {object} deps
  * @param {object} [deps.ctx] 宿主上下文（可能带 workspaceRegistry；旧版 dsh 没有）
@@ -62,9 +84,16 @@ export function createScopeResolver({ ctx, config, logger } = {}) {
 
     // workspace：registry 反查优先（成员资格 = id 命中 + header canonical cwd
     // 校验过，path 已 realpath 归一），失败回退 header.cwd，再失败留 NULL。
+    //
+    // issue #487：这里曾经是裸读 ctx?.workspaceRegistry，而 workspaceRegistry 不在
+    // inject 声明里（index.js:45）。cordis 4 的 ctx 是 Proxy，裸读未注入属性会抛
+    // "cannot get property ... without inject" 而不返回 undefined——于是这层反查
+    // 从 v0.8.0 起一直抛错走降级，canonical 归一与成员资格校验静默失效，只剩
+    // header.cwd。改用免 inject 读取（同 api.js:205 / index.js:583 的 webServer
+    // 先例）；不加进 inject 的理由见 index.js:39-44（v0.7.23 的 apply 阶段崩溃）。
     let workspaceScope = null;
     try {
-      const list = ctx?.workspaceRegistry?.list?.();
+      const list = readOptionalService(ctx, "workspaceRegistry")?.list?.();
       const sessionId = session?.id;
       if (Array.isArray(list) && sessionId != null) {
         const hit = list.find(

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",
@@ -202,7 +209,7 @@ const FEATURE_FLAG_BOOLEANS = [
   // 点号键平铺存、合并时展开回 distillRecords 对象（同 llmAudit.enabled）。
   // retentionDays 是 int，走下面的 INT_RANGES 表，不进开关白名单。
   "distillRecords.enabled",
-  // v0.9.0：M.O.（Modus Operandi · 手法，beta）客户端视图开关。客户端读 /features
+  // v0.9.0：M.O.（Modus Operandi，beta）客户端视图开关。客户端读 /features
   // 的 effective
   // 决定是否注册座位（会话头图标 / 浮层 / 右栏 / 对话行卡片），服务端只负责把
   // 这个键稳定暴露出来——键若不在 effective 里，客户端静默少键、一个座位都不注册。
@@ -212,6 +219,10 @@ const FEATURE_FLAG_BOOLEANS = [
   // 与上面那个键分开：那个管「看图的座位」，这个管「往账本里写」。默认关（beta、
   // opt-in），顶层扁平键，不需要 NESTED_FLAG_PATHS 条目。
   "actionRunEnabled",
+  // v0.9.0 第三批：M.O. 自动沉淀（会话跑完一轮 → 挖这个项目自己的会话日志 → 落提议）。
+  // 与前两个分开：这个管「从日志里长出候选」，那个管记账、另一个管看图。默认关
+  // （beta、opt-in）；顶层扁平键，不需要 NESTED_FLAG_PATHS 条目。进 LIGHT_MODE_OFF。
+  "actionNudgeEnabled",
   // 人格定义页（beta）：注入器渲染人格段的顶层总闸（双闸门的 config 半边；对象内
   // 的 persona.enabled 是 per-agent 半边，存 user_settings 的 "persona" 键，见
   // getPersona/setPersona）。默认关（beta、opt-in，老用户行为逐字节不变）；不进