@modusensus/dsh-mneme 0.9.1 → 0.9.2

package/lib/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/lib/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/lib/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,

package/lib/tools.js

@@ -7,6 +7,7 @@ import { matchesPlatform } from "./runtime/closure.js";
 import { verifyPayload } from "./runtime/verify.js";
 import { TOOL_GUIDE, CONTINUITY_TOOL_RULE } from "./guide.js";
 import { injectChildEnabled } from "./config.js";
+import { normalizeScopeStateDimension, normalizeScopeStateValue, normalizeScopeStateState } from "./scope-state.js";
 import { lastUserQuery } from "./inject.js";
 
 const TEXT_OUTPUT = (text) => [{ type: "text", text }];
@@ -500,6 +501,76 @@ export function createTools(ctx, service, config, embedder) {
       }
     }),
 
+    // #471：政策轴——作用域级可逆闸门。与 memory_forget/memory_archive 的分工：
+    // 那两个是事实轴的单条操作（改的是「这条记忆属于谁 / 还算不算数」，一条条来）；
+    // 本工具是政策轴的按作用域操作（改的是「这一路现在通不通」，跨会话存续、
+    // 松开即原样回来，一条记忆行都不动）。判断指引：整条工作线要临时静音用本工具；
+    // 单条记忆不该再被想起才用 memory_forget/memory_archive。
+    defineTool({
+      name: "set_scope_state",
+      description:
+        "Press or release the reversible scope gate for one scope (issue #471): while paused, that scope's memories stay stored and unchanged but are held back from injection and dream consolidation. " +
+        "This is not deletion and not forgetting — release with state=active and everything comes back exactly as it was, which is why it is the right tool for temporarily silencing a whole work stream rather than editing memories one by one. " +
+        "dimension is agent or workspace; scope_value is the label itself, or * for that dimension's global gate. " +
+        "Both switches (scopeState.enabled/enforce) are off by default, so setting a state has no effect on injection until the user turns them on in the panel.",
+      parameters: {
+        dimension: { type: "string", required: true, description: "Scope dimension to press: \"agent\" or \"workspace\"" },
+        scope_value: { type: "string", required: true, description: "The scope label, or \"*\" for that dimension's global gate" },
+        state: { type: "string", required: true, description: "\"paused\" presses the gate, \"active\" releases it" },
+        note: { type: "string", description: "Optional short reason, stored with the decision so the next reader knows why it was pressed" }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            scope: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                dimension: { type: "string", required: true },
+                scope_value: { type: "string", required: true },
+                state: { type: "string", required: true },
+                // 理由要能读回来：不带它，下次读的人只知道「按下过」却不知道为什么。
+                // 这与库层 setScopeState 的 note 取舍是同一条理由——不带理由的重按
+                // 不抹掉旧理由，正是为了让这里读得回来。可选：从没写过就没有。
+                note: { type: "string" },
+                decided_at: { type: "string", required: true }
+              }
+            }
+          }
+        },
+        // 回执如实回显当前值（不是回显入参）：同一个状态重复按下时 decided_at 保持
+        // 首次值，回显它才看得出「这次没有真的改变什么」。
+        render: (_args, value) =>
+          TEXT_OUTPUT(
+            `Scope ${value.scope.dimension}:${value.scope.scope_value} is now ${value.scope.state} (decided at ${value.scope.decided_at}).`
+          )
+      },
+      async execute(args) {
+        const dimension = normalizeScopeStateDimension(args.dimension);
+        const scopeValue = normalizeScopeStateValue(args.scope_value);
+        const state = normalizeScopeStateState(args.state);
+        if (dimension === null) throw new Error("dimension must be \"agent\" or \"workspace\"");
+        if (scopeValue === null) throw new Error("scope_value must be a non-empty label or \"*\"");
+        if (state === null) throw new Error("state must be \"active\" or \"paused\"");
+        const row = service.setScopeState({ dimension, scope_value: scopeValue, state, note: args.note });
+        if (row === undefined) throw new Error("scope state could not be recorded");
+        return {
+          scope: {
+            dimension: row.dimension,
+            scope_value: row.scope_value,
+            state: row.state,
+            // 没写过理由时键整个不出现（而不是 note: undefined）：output schema 是
+            // 闭合的，DTO 矩阵会拿真实返回值过 validateJsonSchemaValue，留一个
+            // 值为 undefined 的键等于留个空壳。
+            ...(row.note === undefined ? {} : { note: row.note }),
+            decided_at: row.decided_at
+          }
+        };
+      }
+    }),
+
     // #230（#164 设计稿评审线）：document 型记忆注册——agent 产长文档的指针
     // 行铸造口。写入权分离：全文归 agent（管线对文件零读零写零改），库里只
     // 存摘要 + doc_path + evidence 三样；C2 比对去重、supersede 记账在

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@modusensus/dsh-mneme",
   "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite store, Markdown mirrors, 10 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/api.js

@@ -207,6 +207,15 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   // feature flags 快照（GET/PUT 共用）：overrides 是持久化的用户显式覆盖；
   // effective 是启动配置在白名单键上被 overrides 覆盖后的最终值。config 缺席
   // （旧调用方直连、未传 cfg）时只报被覆盖的键，不把不存在的默认值编造给前端。
+  //
+  // pendingRestart 回答的是第三个问题：「我改的开关，现在真的生效了吗？」
+  // 功能开关的生效节奏与 panel_mode 相同——启动时由 index.js 合并进 cfg，运行中
+  // 那份 cfg 是冻结的（见 index.js 装配处的注释）。于是面板显示「已改」不等于
+  // 运行时已改：#481 实测人格总闸正是这样，面板开着、人格段却不注入，用户只能
+  // 靠反复试错发现。effective 表达的是「运行时取什么值」（overrides 优先），
+  // **反推不出待重启**，必须另比一次冻结值——这是本字段存在的唯一理由。
+  // 只报「显式覆盖 ≠ 冻结值」的键：未被覆盖的键运行时值就是 cfg 值，不存在落差；
+  // config 缺席（旧调用方直连、未传 cfg）时无从比较，返回空数组而不编造。
   const flagKeys = [
     ...FEATURE_FLAG_SPEC.booleans,
     ...Object.keys(FEATURE_FLAG_SPEC.ints),
@@ -232,7 +241,11 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     // Issue #399：蒸馏原文留存 + 溯源。两个键都是嵌套子字段（enabled 开关 +
     // retentionDays 整数），漏登记的后果同上——effective 静默缺键。
     "distillRecords.enabled": ["distillRecords", "enabled"],
-    "distillRecords.retentionDays": ["distillRecords", "retentionDays"]
+    "distillRecords.retentionDays": ["distillRecords", "retentionDays"],
+    // Issue #471：政策轴——作用域级可逆闸门。两个键都是嵌套子字段，漏登记的后果
+    // 同上（effective 静默缺键、面板读不到也 PUT 不进）。
+    "scopeState.enabled": ["scopeState", "enabled"],
+    "scopeState.enforce": ["scopeState", "enforce"]
     // sensitiveScanEnabled（#164 A2）是顶层扁平键，不需要进这张表——走 configFlagValue
     // 的默认分支即可。
   };
@@ -241,6 +254,19 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     if (path) return config?.[path[0]]?.[path[1]];
     return config?.[key];
   }
+  // 「显式覆盖 ≠ 冻结值」的键。用 Object.is 比而不是 !==：NaN 与 ±0 的边角上
+  // 两者会给出相反的结论（Object.is(NaN, NaN) 为真、Object.is(0, -0) 为假），
+  // 开关值里虽然不该出现它们，但比较语义与「值是否相同」对齐更省心。
+  // 未被覆盖的键不看：它的运行时值本来就取自 cfg，不存在落差。
+  function pendingRestartKeys(overrides) {
+    if (!config) return [];
+    const pending = [];
+    for (const key of flagKeys) {
+      if (overrides[key] === undefined) continue;
+      if (!Object.is(overrides[key], configFlagValue(key))) pending.push(key);
+    }
+    return pending;
+  }
   function featureSnapshot() {
     const overrides = settings.getFeatureFlags();
     const effective = {};
@@ -251,7 +277,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         if (value !== undefined) effective[key] = value;
       }
     }
-    return { overrides, effective };
+    return { overrides, effective, pendingRestart: pendingRestartKeys(overrides) };
   }
 
   // Ensure the service has an embedder when the API layer was handed one
@@ -1054,6 +1080,25 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         const configured = embedder ? (typeof embedder.configured === "boolean" ? embedder.configured : true) : null;
         const embedded = Number(stats?.embeddedCount ?? 0);
         const total = Number(stats?.totalCount ?? 0);
+        // Per-model / per-dimension provenance of stored vectors. "embedded"
+        // counts rows with any vector; rows whose dimension differs from the
+        // current embedder output are skipped by searchVector, so the honest
+        // retrievable number is the current-dimension slice. modelBreakdown
+        // groups by row-level embedding_model ('' = unknown origin).
+        const dimensionBreakdown = typeof service.embeddingDimensionBreakdown === "function"
+          ? service.embeddingDimensionBreakdown()
+          : null;
+        const currentDim = embedder?.dimension != null ? String(embedder.dimension) : null;
+        const byDimension = dimensionBreakdown
+          ? [...dimensionBreakdown.entries()].map(([dim, c]) => ({ dimension: dim === "" ? null : Number(dim), count: c }))
+          : [];
+        const unsearchable = (currentDim && dimensionBreakdown)
+          ? [...dimensionBreakdown.entries()]
+              .filter(([dim]) => dim !== currentDim)
+              .reduce((s, [, c]) => s + c, 0)
+          : 0;        const modelBreakdown = typeof service.embeddingModelBreakdown === "function"
+          ? service.embeddingModelBreakdown().map((r) => ({ model: r.model === "" ? null : r.model, count: r.c }))
+          : [];
         sendJson(res, 200, {
           ready,
           configured,
@@ -1064,6 +1109,16 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
                 : null,
           // 空库时 ratio 必须是 null 而非 0 —— 0 会被读成「一条都没嵌上」。
           coverage: { embedded, total, ratio: total > 0 ? embedded / total : null },
+          // distill-tx-embed-gap 后续：向量「存在」≠「可检索」。unsearchable =
+          // 维度与当前 embedder 输出不同的行数（searchVector 会跳过它们），
+          // retrievable = 与当前维度同维、真正参与召回的行数。两者差值非零时
+          // 面板必须能说出「有 N 条向量不可检索」，而不是只给一个虚高的 coverage。
+          vectors: {
+            byDimension,
+            byModel: modelBreakdown,
+            unsearchable,
+            retrievable: currentDim ? (dimensionBreakdown.get(currentDim) ?? 0) : null,
+          },
           // 配了、库里有东西可嵌、却一条都没嵌上 = 真的降级（本机此前长期
           // 处于 ready:true + embeddedCount:0，面板却显示正常）。
           degraded: configured === true && total > 0 && embedded === 0,

package/src/config.js

@@ -863,6 +863,23 @@ export const Config = z.object({
   // 数据、观察 A2 加权质量后再切硬过滤。
   strictScope: z.boolean().default(false),
 
+  // scopeState（issue #471）：政策轴——作用域级可逆闸门。与上面两个键是**两条不同
+  // 的轴**：scopeEnabled/strictScope 管「这条记忆属于谁」（事实轴：持久、跟着记忆
+  // 行走、改的是归属数据），本键管「这个作用域现在通不通」（政策轴：暂时、由人单
+  // 方面按下、松开即恢复、不改任何记忆行）。
+  // 两级语义同 writeAdmission/preInjectGate——enabled 打开时被按下的作用域其候选
+  // 照常注入，但留一条审计行说清「本应被拦下几条」（观察档，先在真实流量看会少掉
+  // 多少再决定真按）；enforce 打开才真的不注入（拦截档）。两个都默认关，打开前
+  // 行为与今天逐字段一致。
+  // 不进 LIGHT_MODE_OFF：它只是查一张小表的判定，不引入重型后台路径、不加常驻
+  // 文本（同 actionPipelineEnabled 的定性）——轻量档预设该关的是重型能力，不该替
+  // 用户关掉一个纯判定入口，用户显式勾选仍然赢。
+  // 也走 feature_flags（FEATURE_FLAG_BOOLEANS 白名单），面板可启停=线上回滚开关。
+  scopeState: z.object({
+    enabled: z.boolean().default(false),
+    enforce: z.boolean().default(false)
+  }).default({}),
+
   // --- v0.9.0 M.O.（Modus Operandi · 手法，beta）--------------------------
   // 命名：M.O. = Modus Operandi，拉丁语「一个人一贯的做事方式」，缩写 M.O.；
   // 也正是 org 词根 modus（modusensus）。界面主显示 M.O.，设置项 hint 第一句