@modusensus/dsh-mneme 0.9.1 → 0.9.2

package/lib/dream.js

@@ -10,7 +10,7 @@ import { scopeKeyOf } from "./scope.js";
 import { isInPeakWindow, nextOffPeakAt } from "./peak-hours.js";
 import { createHash, randomUUID } from "node:crypto";
 import { STR, langOf } from "./lang.js";
-export { validateDecisions, applyDecisions, withEffortFallback, describeStreamFailure, resolveDreamEffort, resolveRoute };
+export { validateDecisions, applyDecisions, withEffortFallback, withMaxTokensFallback, parseMaxTokensCap, describeStreamFailure, resolveDreamEffort, resolveRoute };
 
 // Extract the first JSON array from LLM output, tolerating markdown fences,
 // leading/trailing prose, and common wrapper noise. Returns an array or null.
@@ -57,10 +57,24 @@ function totalChars(memories) {
 // 两处若各写一份过滤条件，重启播种读到的基线就会和运行期判定口径漂移（一个把
 // document 算进去、一个不算），阈值随之失真，且这种漂移只会在重启后才显形。
 function activeStoreSize(service) {
-  const memories = service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document");
+  const memories = withoutPaused(service, service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document"));
   return { count: memories.length, chars: totalChars(memories) };
 }
 
+// issue #471 政策轴：被按下的作用域不参与巩固，也就不该再撑着阈值把它自己触发起来。
+// 三个读入口（本函数、generateNarratives 的 inputs、runDream 的 memories）各自的附加
+// 条件不同——有的排 forgotten、有的不排——但「政策轴这一层」对三处是一样的，故收成
+// 一个助手而不是各写一遍过滤，理由与 activeStoreSize 开头记着的口径漂移同源：两处
+// 各写一份过滤条件，漂移只会在重启后才显形。
+//
+// 走 service.filterPaused 而不是自己读状态表：判定只许有一份实现（见
+// src/scope-state.js 的模块注释）。service 上取不到这个函数时（老装配、测试夹具）
+// 原样返回，行为与改动前一致。
+function withoutPaused(service, rows) {
+  if (typeof service?.filterPaused !== "function") return rows;
+  return service.filterPaused(rows);
+}
+
 // 基线的唯一合法形状：两个非负整数；其余（缺字段、负数、非整数、整个对象缺失）
 // 一律视为「没有基线」→ 调用方退回 {0,0}。播种值来自持久化列，可能是老库的 NULL
 // 或手工改坏的库，判定必须比调用点更严格，而不是相信数据库里存的一定合法。
@@ -399,6 +413,60 @@ async function withEffortFallback(ctx, effort, attempt, fallback, getStreamError
   }
 }
 
+// Issue #478：max_tokens 超服务商硬上限的拒收判别式与上限提取的单一来源。
+// 实测失败样例（dream_runs 180 连败）："max_tokens 不能超过 65536"——131072 的
+// 默认值原样发出，网关 400 直接拒，推理还没开始。与 EFFORT_REJECT_RE 同款思路：
+// 各处手写会漂移，导出供测试与其它调用点复用。
+export const MAX_TOKENS_REJECT_RE = /max[\s_-]*tokens?/i;
+
+/**
+ * 从拒收报错里提取服务商声明的 max_tokens 上限。只认「显式给数」的说法
+ * （不能超过 / at most / maximum value is / <= 65536 …），认不出就返回 null
+ * ——宁可不降级重试，也不能把报错里那个被拒的请求值（131072）误当上限。
+ * @returns {number|null}
+ */
+function parseMaxTokensCap(message) {
+  const m = String(message ?? "").match(
+    /(?:不能超过|不得超过|超出上限|至多|最多(?:只能|仅)?|at\s+most|no\s+more\s+than|maximum(?:\s+value)?(?:\s+is)?|max(?:\.)?(?:\s+value)?(?:\s+is)?|less\s+than\s+or\s+equal\s+to|<=?)\s*[:：]?\s*(\d{2,10})/i
+  );
+  const cap = m ? Number(m[1]) : null;
+  return cap && Number.isFinite(cap) && cap > 0 ? cap : null;
+}
+
+/**
+ * Issue #478：max_tokens 被服务商 400 拒收时，按报错里的上限自动降级重试一次。
+ * 与 withEffortFallback 同构：stream 路径的结果折叠成 undefined、真实原因在
+ * getStreamError() 里；throw 路径直接看 message。命中拒收且提取到比当前值小的
+ * 上限才重试（attempt 接收 tokens 值），否则原样返回/抛出。单次重试，与
+ * effort 的先例一致——重试后若仍被拒（同上限再报），cap >= tokens 的守卫让
+ * 它自然终止，不会循环。
+ */
+async function withMaxTokensFallback(ctx, maxTokens, attempt, getStreamError) {
+  const retry = (tokens, reason) => {
+    ctx.logger?.warn?.(`dsh-mneme dream: max_tokens ${maxTokens} rejected by provider (${reason}); retrying with ${tokens}`);
+    return attempt(tokens);
+  };
+  try {
+    const result = await attempt(maxTokens);
+    if (result === undefined) {
+      const reason = String(getStreamError?.() ?? "");
+      if (MAX_TOKENS_REJECT_RE.test(reason)) {
+        const cap = parseMaxTokensCap(reason);
+        if (cap && cap < maxTokens) return retry(cap, reason);
+      }
+    }
+    return result;
+  } catch (error) {
+    // AbortError 直接放行（取消意图绝不能被降级重试吞掉，与 effort 同款守卫）。
+    if (error?.name === "AbortError") throw error;
+    const message = String(error?.message ?? error);
+    if (!MAX_TOKENS_REJECT_RE.test(message)) throw error;
+    const cap = parseMaxTokensCap(message);
+    if (!cap || cap >= maxTokens) throw error;
+    return retry(cap, message);
+  }
+}
+
 /** 向量索引同步（总览与叙述条共用）：fail-safe，失败只 warn 不反噬主流程。 */
 async function reEmbedMemory(semantic, memory, logger) {
   if (!semantic?.embedder || !semantic?.vectorIndex || !memory) return;
@@ -418,7 +486,7 @@ async function reEmbedMemory(semantic, memory, logger) {
  * 任何失败降级为 0 条，绝不反噬 dream 主流程。
  */
 async function generateNarratives({ ctx, service, config, route, language, effort, semantic, logger }) {
-  const inputs = service.all().filter((m) => !m.archived && !m.forgotten && m.type !== "summary" && m.type !== "document");
+  const inputs = withoutPaused(service, service.all().filter((m) => !m.archived && !m.forgotten && m.type !== "summary" && m.type !== "document"));
   const clusters = clusterByTag(inputs, { minCluster: config.dreamNarrativeMinCluster ?? 3 });
   if (!clusters.length) return 0;
 
@@ -427,7 +495,7 @@ async function generateNarratives({ ctx, service, config, route, language, effor
       [`# ${tag}`, ...members.map((m) => `- id=${m.id} | title=${m.title} | ${m.content}`)].join("\n"))
     .join("\n\n");
   let streamFailure = "";
-  const runNarratives = (withEffort) => {
+  const runNarratives = (withEffort, tokens) => {
     streamFailure = "";
     return runAuditedLlm(ctx, service, config, {
       triggerSource: "autoDream",
@@ -439,7 +507,7 @@ async function generateNarratives({ ctx, service, config, route, language, effor
       provider: route.provider,
       model: route.model,
       purpose: "compaction",
-      maxTokens: config.dreamMaxTokens ?? 2048,
+      maxTokens: tokens,
       ...(withEffort && effort ? { reasoningEffort: effort } : {}),
       messages: [
         { role: "system", content: [{ type: "text", text: STR.prompts.narrative[language] }], source: { kind: "plugin:dsh-mneme", plugin: "dsh-mneme" } },
@@ -447,7 +515,7 @@ async function generateNarratives({ ctx, service, config, route, language, effor
       ]
     }, reportUsage, (reason) => { streamFailure = describeStreamFailure(reason); }));
   };
-  const text = await withEffortFallback(ctx, effort, () => runNarratives(true), () => runNarratives(false), () => streamFailure);
+  const text = await withMaxTokensFallback(ctx, config.dreamMaxTokens ?? 2048, (tokens) => withEffortFallback(ctx, effort, () => runNarratives(true, tokens), () => runNarratives(false, tokens), () => streamFailure), () => streamFailure);
 
   const entries = extractJsonArray(text);
   if (!Array.isArray(entries)) return 0;
@@ -946,7 +1014,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
   async function runDream(ctx, service, config) {
     const language = langOf(config);
     const logger = ctx.logger;
-    let memories = service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document");
+    let memories = withoutPaused(service, service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document"));
     if (memories.length === 0) return { ok: true, applied: 0, skipped: true, summary: false };
     // Issue #89：开跑时刻既喂给审计行（created_at），也是调度器闸门的时间基准。
     const dreamStartedAt = Date.now();
@@ -1127,7 +1195,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     const effort = await resolveDreamEffort(ctx, route, config.dreamReasoningEffort, logger);
     let decisions = null;
     let streamFailure = "";
-    const runConsolidation = (withEffort) => {
+    const runConsolidation = (withEffort, tokens) => {
       streamFailure = "";
       return runAuditedLlm(ctx, service, config, {
       triggerSource: "autoDream",
@@ -1143,7 +1211,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       provider: route.provider,
       model: route.model,
       purpose: "compaction",
-      maxTokens: config.dreamMaxTokens ?? 4096,
+      maxTokens: tokens,
       ...(withEffort && effort ? { reasoningEffort: effort } : {}),
       messages: [
         { role: "system", content: [{ type: "text", text: consolidationPrompt }], source: { kind: "plugin:dsh-mneme", plugin: "dsh-mneme" } },
@@ -1155,7 +1223,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       // Bug8: the consolidation call is audited (tokens/time/status). A throw
       // re-propagates to the catch below; an aborted stream returns undefined
       // and is treated as a failed run after the check below.
-      decisionText = await withEffortFallback(ctx, effort, () => runConsolidation(true), () => runConsolidation(false), () => streamFailure);
+      decisionText = await withMaxTokensFallback(ctx, config.dreamMaxTokens ?? 4096, (tokens) => withEffortFallback(ctx, effort, () => runConsolidation(true, tokens), () => runConsolidation(false, tokens), () => streamFailure), () => streamFailure);
     } catch (error) {
       logger?.warn?.(`dsh-mneme dream: consolidation llm call failed: ${String(error)}`);
       return finish({ ok: false, error: "llm failed", summary: false });
@@ -1368,7 +1436,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     // a failed run; summary:false marks a run that produced no summary.
     let summaryText;
     let summaryStreamFailure = "";
-    const runSummary = (withEffort) => {
+    const runSummary = (withEffort, tokens) => {
       summaryStreamFailure = "";
       // Issue #258：总览阶段可用 dreamSummaryProvider/dreamSummaryModel 走独立路由
       //（默认空 = 沿用 dream 路由）；输入侧有 dreamSummaryMaxInputs 硬上限，
@@ -1386,7 +1454,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       provider: summaryRoute.provider,
       model: summaryRoute.model,
       purpose: "compaction",
-      maxTokens: config.dreamMaxTokens ?? 2048,
+      maxTokens: tokens,
       ...(withEffort && effort ? { reasoningEffort: effort } : {}),
       messages: [
         { role: "system", content: [{ type: "text", text: STR.prompts.dreamSummary[language] }], source: { kind: "plugin:dsh-mneme", plugin: "dsh-mneme" } },
@@ -1404,7 +1472,11 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     // 渐进恶化。倒序排序与 consolidate 窗口同款（updated_at desc, id tiebreak），
     // 保留最新的；0 = 关闭上限（回归全库行为，调用方自担 ctx）。
     // #230：document 指针行不进总览（与 dream/sleep 五个候选池的同款排除）。
-    const summaryAll = service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document");
+    // issue #471：这一处尤其不能漏——总览落库时是**无作用域**的 summary 行
+    // （saveWithDedupe 不带 agent_scope/workspace_scope），所以被按下作用域的内容
+    // 一旦进了总览，注入侧按作用域过滤就再也拦不住它：内容已经洗成了全局行。
+    // 别的入口漏了只是「那一条漏过去」，这里漏了是「洗一遍之后一直漏」。
+    const summaryAll = withoutPaused(service, service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document"));
     const summaryMaxInputs = Number.isInteger(config.dreamSummaryMaxInputs) ? config.dreamSummaryMaxInputs : 0;
     const summaryInputs = summaryMaxInputs > 0 && summaryAll.length > summaryMaxInputs
       ? [...summaryAll]
@@ -1425,7 +1497,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     );
     try {
       // Bug8: the summary call is audited too (operation dream_summarize).
-      summaryText = await withEffortFallback(ctx, effort, () => runSummary(true), () => runSummary(false), () => summaryStreamFailure);
+      summaryText = await withMaxTokensFallback(ctx, config.dreamMaxTokens ?? 2048, (tokens) => withEffortFallback(ctx, effort, () => runSummary(true, tokens), () => runSummary(false, tokens), () => summaryStreamFailure), () => summaryStreamFailure);
     } catch (error) {
       logger?.warn?.(`dsh-mneme dream: summary llm call failed: ${String(error)}`);
       return finish({ ok: false, error: "llm failed", applied, decisions: auditDecisions, outcome, frozen: frozenCount, summary: false });

package/lib/embedding.js

@@ -31,10 +31,32 @@ function embeddingsUrl(baseUrl) {
  * Call the embeddings API for one text. Resolves to a Float64 array, or null
  * when the provider is not configured, the call fails, or the response is
  * unusable. Never throws: failures degrade to keyword search.
+ *
+ * The plain null return cannot tell the caller WHY — "model not loaded",
+ * "endpoint 404", "timeout" and "input rejected" all look identical, so the
+ * receipt ledger used to flatten them into one
+ * `embedding-request-returned-no-vector`. Use `embedTextDetailed` when the
+ * reason matters; this wrapper keeps the old contract for existing callers.
  */
-export async function embedText({ baseUrl, apiKey, model }, text) {
+export async function embedText(cfg, text) {
+  const out = await embedTextDetailed(cfg, text);
+  return out.vector;
+}
+
+/**
+ * Same call, but the failure mode is distinguishable: returns
+ * { vector: number[]|null, reason: null|string } where reason is one of
+ *   config-incomplete | request-failed:<err> | http-<status> |
+ *   response-not-json | response-no-vector | empty-text
+ * Never throws. `reason: null` means success.
+ */
+export async function embedTextDetailed({ baseUrl, apiKey, model }, text) {
   const url = embeddingsUrl(baseUrl);
-  if (!url || !apiKey || !model || !text) return null;
+  if (!url || !apiKey || !model || !text) {
+    // 空输入不是端点故障：区分开，否则「text 为空」会被误报成网络问题。
+    const missing = !url ? "baseUrl" : !apiKey ? "apiKey" : !model ? "model" : "text";
+    return { vector: null, reason: `config-incomplete:${missing}` };
+  }
   let res;
   try {
     res = await fetch(url, {
@@ -46,18 +68,33 @@ export async function embedText({ baseUrl, apiKey, model }, text) {
       body: JSON.stringify({ model, input: String(text).slice(0, 8000) }),
       signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS)
     });
-  } catch {
-    return null;
+  } catch (error) {
+    // 超时是 AbortSignal 抛的 TimeoutError；网络层错误（DNS/拒连）是 TypeError。
+    // 两者都走 request-failed，但带上类型，日志里能分清「慢」和「不通」。
+    const kind = error?.name === "TimeoutError" || error?.name === "AbortError" ? "timeout" : "network";
+    return { vector: null, reason: `request-failed:${kind}:${String(error?.message ?? error).slice(0, 200)}` };
+  }
+  if (!res.ok) {
+    // 状态码本身就是最有用的诊断：401/403 是钥匙、404 是路径、429 是限流、
+    // 5xx 是服务端。文本截断且不含请求体，日志安全。
+    let detail = "";
+    try {
+      const t = await res.text();
+      detail = String(t).slice(0, 200);
+    } catch { /* body unreadable, status alone is already informative */ }
+    return { vector: null, reason: `http-${res.status}${detail ? `:${detail}` : ""}` };
   }
-  if (!res.ok) return null;
   let body;
   try {
     body = await res.json();
   } catch {
-    return null;
+    return { vector: null, reason: "response-not-json" };
   }
   const vec = body?.data?.[0]?.embedding;
-  return Array.isArray(vec) && vec.length ? Array.from(vec) : null;
+  if (!Array.isArray(vec) || !vec.length) {
+    return { vector: null, reason: "response-no-vector" };
+  }
+  return { vector: Array.from(vec), reason: null };
 }
 
 /**
@@ -145,24 +182,17 @@ export function createEmbedder({ store, settings, logger, vectorIndex }) {
       return entry;
     }
     const text = [title, content].filter(Boolean).join("\n");
-    let vector = null;
-    try {
-      vector = await embedText(cfg, text);
-    } catch (error) {
-      const entry = { status: "failed", id, at, reason: String(error) };
-      ledger.record(entry);
-      logger?.warn?.(`[dsh-mneme] embed memory ${id} failed: ${String(error)}`);
-      return entry;
-    }
-    if (!vector) {
-      // embedText swallows the HTTP detail (404 / timeout / malformed body all
-      // resolve to null). The receipt still has to say "no vector", which is
-      // exactly the fact the write path never used to report.
-      const entry = { status: "failed", id, at, reason: "embedding-request-returned-no-vector" };
+    const detailed = await embedTextDetailed(cfg, text);
+    if (detailed.reason) {
+      // 回执带上可区分的失败模式（http-404 / request-failed:timeout /
+      // config-incomplete:model / response-no-vector ...），不再把「模型没配」
+      // 「请求挂了」「响应没有向量」压成同一个词。状态页与日志按 reason 分诊。
+      const entry = { status: "failed", id, at, reason: detailed.reason };
       ledger.record(entry);
-      logger?.warn?.(`[dsh-mneme] embed memory ${id} produced no vector`);
+      logger?.warn?.(`[dsh-mneme] embed memory ${id} failed: ${detailed.reason}`);
       return entry;
     }
+    const vector = detailed.vector;
     const model = modelHashOf(cfg.model);
     store.setEmbedding(id, vector, model);
     _dimension = vector.length;

package/lib/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 };
+}