dsh-plugin-prompt-tool 2.1.0 → 3.0.1

package/engine/actions/tool-visibility.mjs

@@ -0,0 +1,248 @@
+/**
+ * tool-visibility —— 工具可见面：一份声明拥有「模型看得见什么、调得动什么」。
+ *
+ * 三面投影都在 system-prompt/assemble 的 after-next 之后完成：
+ *  1. 装配目录（tools 数组）——本轮的呈现面；
+ *  2. tools:sdk 段正文——模型读到的工具声明；
+ *  3. 执行面：deny 用 restrict + guard；allow 只登记 guard（restrict 无法安全覆盖预设/祖先层）。
+ *
+ * 旧实现把同一个意图拆成三条声明（assembly / sdk-strip / guard），其中 guard 属固定
+ * 注册效果、不能带规则级 if，于是「有条件下架」被迫再复制一份名单。这里把名单收在
+ * 一个动作里：条件由规则引擎在装配通道逐轮求值，执行闸按当前条件**重挂或撤销**，
+ * 因此不再有跨轮粘性。
+ *
+ * 名单语义对齐官方 ToolRestriction（deepseek-harness packages/core/tools/src/index.ts:701-706）：
+ * allow 与 deny 可以同时给，判据是「先按 allow 保留，再按 deny 剔除」。requireMatch 只在
+ * allow 模式有意义：名单里任一工具在目录与 SDK 正文的并集里都找不到，就放弃裁剪、暴露完整目录（fail-open）并告警——
+ * 收窄错了会让当前工作流调不到工具，比多花上下文严重。
+ *
+ * 执行边界：deny 同时用 restrict（继承面）与 guard（本层/晚到）；allow 不用 restrict——
+ * 它的 allow 只能收继承面名字，而 `schemas()` 全局视图会漏掉预设/祖先层，局部 allow 会
+ * 把要保留的工具裁掉。allow 统一由 guard 裁决；requireMatch fail-open 时 guard 同步放行。
+ */
+
+import { RUN_CODE, createMask, labelOf, toolSurfacePlan } from './shared.mjs'
+import { createAgentCapability } from '../agent-capability.mjs'
+import { SDK_SECTION_NAME, stripSdkDeclarations, sdkToolNames } from '../sdk-strip.mjs'
+import { TOOL_INVOCATION_EVENT_TYPES, historyEvents } from '../history.mjs'
+import { toolScopeSnapshot } from '../tool-scope.mjs'
+import { DISCOVERY_SERVICE } from '../service-names.mjs'
+import { UNLOCKABLE_DISCOVERY_KINDS } from '../discovery.mjs'
+
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+function parseDiscovery(action, label, plugin) {
+  const discovery = action.discovery
+  if (discovery === undefined) return undefined
+  if (!record(discovery)) throw new TypeError(`${plugin}: ${label}.discovery must be an object — { kind, tool?, key? }`)
+  const kind = discovery.kind
+  if (typeof kind !== 'string' || kind.length === 0) {
+    throw new TypeError(`${plugin}: ${label}.discovery.kind is required`)
+  }
+  // 只有支持「按名解锁」的数据源才能被可见面消费：技能面没有解锁名单语义。
+  if (!UNLOCKABLE_DISCOVERY_KINDS.has(kind)) {
+    throw new TypeError(`${plugin}: ${label}.discovery.kind ${JSON.stringify(kind)} has no unlock semantics — 可用：${[...UNLOCKABLE_DISCOVERY_KINDS].join(', ')}`)
+  }
+  const result = { kind }
+  for (const field of ['tool', 'key']) {
+    if (discovery[field] === undefined) continue
+    if (typeof discovery[field] !== 'string' || discovery[field].length === 0) {
+      throw new TypeError(`${plugin}: ${label}.discovery.${field} must be a non-empty string`)
+    }
+    // 工具身份归 adapter 元数据；声明里写这两个键只作断言（不匹配时告警，不改变实际行为）。
+    result[field] = discovery[field]
+  }
+  return result
+}
+
+
+/** 同一份 mask 的稳定身份：名单变化必须重挂执行闸，不能沿用旧名单。 */
+function maskKey(mask) {
+  const list = (set) => set === undefined ? '' : [...set].sort().join(',')
+  return `allow:${list(mask.allow)}|deny:${list(mask.deny)}|require:${mask.requireMatch ? 1 : 0}`
+}
+
+/**
+ * 从完整历史回收解锁名（判据与旧 assembly.allowFrom 逐条对齐）：认顶层 `tool/call`
+ * 与 PTC 嵌套 `tool/ptc-dispatch` 里精确等于发现工具的调用，参数解析失败逐条跳过；
+ * 解锁只做加法，不能越过 deny。读完整历史而非可见面：压缩遮蔽那条调用后仍要保留。
+ */
+function fillUnlocked(into, session, tool, key, warnOnce, plugin, label) {
+  into.clear()
+  // 发现工具是解锁通道本身：它必须恒在放行集里，否则白名单会把它一起裁掉、从此无法解锁。
+  into.add(tool)
+  let events
+  try {
+    events = historyEvents(session)
+  } catch (error) {
+    warnOnce(`${plugin}: tool-visibility action ${label}: reading session events for discovery failed: ${String(error?.message ?? error)}`)
+    return
+  }
+  for (const event of events) {
+    // PTC 下 run_code 里的嵌套调用落为 tool/ptc-dispatch，不是顶层 tool/call。
+    if (!TOOL_INVOCATION_EVENT_TYPES.includes(event?.type) || event?.data?.name !== tool) continue
+    const raw = event.data.arguments
+    let parsed
+    try { parsed = typeof raw === 'string' ? JSON.parse(raw) : raw } catch { continue }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) continue
+    const value = parsed[key]
+    if (!Array.isArray(value)) continue
+    for (const item of value) if (typeof item === 'string' && item.length > 0) into.add(item)
+  }
+}
+
+export function prepareToolVisibility(action, plugin) {
+  const label = labelOf(action)
+  const discovery = parseDiscovery(action, label, plugin)
+  // 发现工具只解锁白名单里没点的名字：allowExtra 是「只做加法」的活集合，每轮从持久调用记录回收。
+  if (discovery !== undefined && action.allow === undefined) {
+    throw new TypeError(`${plugin}: ${label}.discovery requires allow — 解锁只对白名单有意义`)
+  }
+  const allowExtra = discovery === undefined ? undefined : new Set()
+  const mask = createMask(action, label, plugin, allowExtra)
+  // requireMatch 只对白名单有意义（与 assembly / sdk-strip 同判据）：黑名单没有「必需名单」。
+  if (mask.requireMatch && mask.allow === undefined) {
+    throw new TypeError(`${plugin}: ${label}.requireMatch only applies to allow — deny lists have no required names`)
+  }
+
+  return (mountCtx, { warnOnce, on, collect, onMiss }) => {
+    /** 执行面：restrict 覆盖继承的全局工具，guard 兜住本层与晚到工具。 */
+    const capability = createAgentCapability((agent) => {
+      const tools = agent?.ctx?.tools
+      if (tools === undefined) return undefined
+      const state = { failOpen: false }
+      const disposers = []
+      try {
+        const known = toolScopeSnapshot(tools).globalNames
+        if (mask.deny !== undefined && typeof tools.restrict === 'function' && known !== undefined) {
+        // allow 模式不走 restrict：`schemas()` 是全局视图，过滤后的 allow 会漏掉预设/祖先层的
+        // 工具，restrict 反而把它们裁掉；restrict 只接收继承面名字，无法安全区分本层工具。
+        // allow 的执行面统一由下面的 guard 兜底。
+        const deny = [...mask.deny].filter((name) => known.has(name))
+        if (deny.length > 0) {
+          try {
+            const dispose = tools.restrict({ deny })
+            if (typeof dispose === 'function') disposers.push(dispose)
+          } catch (error) {
+            // restrict 失败不改变呈现面；执行面还有 guard 兜底。
+            warnOnce(`${plugin}: tool-visibility action ${label} restrict skipped: ${String(error?.message ?? error)}`)
+          }
+        }
+      }
+        if ((mask.deny !== undefined || mask.allow !== undefined) && typeof tools.guard === 'function') {
+          const deny = mask.deny
+          disposers.push(tools.guard((exec) => {
+            const toolName = exec?.name
+            if (toolName === RUN_CODE || typeof toolName !== 'string' || toolName.length === 0) return undefined
+            if (deny?.has(toolName)) return `${label}: tool ${JSON.stringify(toolName)} is denied by tool-visibility`
+            if (mask.allow !== undefined && !state.failOpen && mask.blocks(toolName)) {
+              return `${label}: tool ${JSON.stringify(toolName)} is not allowed by tool-visibility`
+            }
+            return undefined
+          }))
+        }
+      } catch (error) {
+        // 声明失败不能丢已注册的 restrict：已收集的 disposer 仍交给声明表统一撤销。
+        warnOnce(`${plugin}: tool-visibility action ${label} failed to mount execution gate: ${String(error?.message ?? error)}`)
+      }
+      return { disposers, data: state }
+    })
+
+    const syncGate = (agent) => {
+      const key = `${maskKey(mask)}|unlock:${allowExtra === undefined ? '' : [...allowExtra].sort().join(',')}`
+      capability.sync(agent, key)
+    }
+
+    collect(capability.releaseAll)
+    // 条件为假时 rule-runtime 不进入 handler：未命中回调负责撤掉上一轮注册的执行闸。
+    // 动作级 when 由 withWhen 调用时没有帧，只能撤当前已登记的全部会话。
+    onMiss((frame) => {
+      const session = frame?.subject?.agent?.session ?? frame?.args?.[1]?.agent?.session
+      if (session === undefined) capability.releaseAll()
+      else capability.release(session)
+    })
+
+    collect(on('system-prompt/assemble', async (assembly, context, next) => {
+      const assembled = await next()
+      // 解锁名必须先回收：执行闸的 restrict allow 要包含本轮解锁项，否则解锁的工具看得见、调不动。
+      // 工具名与参数键来自发现注册表的 adapter 元数据；声明里的同名字段只作断言。
+      if (allowExtra !== undefined) {
+        const registry = typeof mountCtx.get === 'function' ? mountCtx.get(DISCOVERY_SERVICE) : undefined
+        const adapter = typeof registry?.get === 'function' ? registry.get(context?.agent, discovery.kind) : undefined
+        const unlock = adapter?.unlock
+        if (unlock === undefined) {
+          allowExtra.clear()
+          warnOnce(`${plugin}: tool-visibility action ${label}: discovery adapter "${discovery.kind}" is not registered for this agent — unlock recovery skipped`)
+        } else {
+          if (discovery.tool !== undefined && discovery.tool !== unlock.tool) {
+            warnOnce(`${plugin}: tool-visibility action ${label}: discovery.tool ${JSON.stringify(discovery.tool)} does not match the "${discovery.kind}" adapter tool ${JSON.stringify(unlock.tool)}`)
+          }
+          if (discovery.key !== undefined && discovery.key !== unlock.key) {
+            warnOnce(`${plugin}: tool-visibility action ${label}: discovery.key ${JSON.stringify(discovery.key)} does not match the "${discovery.kind}" adapter key ${JSON.stringify(unlock.key)}`)
+          }
+          fillUnlocked(allowExtra, context?.session ?? context?.agent?.session, unlock.tool, unlock.key, warnOnce, plugin, label)
+        }
+      }
+      try {
+        syncGate(context?.agent)
+      } catch (error) {
+        // 闸注册失败必须留痕；呈现面照常结算，绝不把异常抛给装配。
+        warnOnce(`${plugin}: tool-visibility action ${label} failed to sync execution gate: ${String(error?.message ?? error)}`)
+      }
+      try {
+        let result = assembled
+        // PTC 的 tools 数组只有 run_code 传输；实际可见面在 SDK 正文里，requireMatch 必须
+        // 以两者并集为准，否则 native 的收窄名单会被误判成缺失并 fail-open。
+        const sdkSection = Array.isArray(result.sections)
+          ? result.sections.find((section) => section?.name === SDK_SECTION_NAME && typeof section.text === 'string')
+          : undefined
+        const sdkNames = sdkSection === undefined ? undefined : new Set(sdkToolNames(sdkSection.text))
+        const available = new Set([
+          ...(Array.isArray(result.tools) ? result.tools.map((tool) => tool?.name).filter((name) => typeof name === 'string') : []),
+          ...(sdkNames ?? []),
+        ])
+        // 没有工具面可观（既无目录也无 SDK 正文）时不裁剪、不告警、不动执行闸：
+        // 空 surface 不等于「名单全缺」；空目录（tools=[]）仍是真实观测，照旧 fail-open。
+        if (!Array.isArray(result.tools) && sdkSection === undefined) return result
+        // 三面（目录 / 正文 / 执行闸）共用这一份判断：缺项就整体放宽，呈现与执行不得两套口径。
+        const plan = toolSurfacePlan(mask, available)
+        const state = capability.get(context?.session ?? context?.agent?.session)
+        if (state !== undefined) state.data.failOpen = plan.failOpen
+        if (plan.failOpen) {
+          // 去重键固定到动作：缺项名随解锁历史变化，不能让每个新集合各占一条 warnOnce。
+          warnOnce(`${plugin}: tool-visibility action ${label}: requireMatch tools absent (${plan.missing.join(', ')}) — exposing the full tool set (fail-open)`, `${plugin}: tool-visibility action ${label}: requireMatch fail-open`)
+        } else {
+          if (Array.isArray(result.tools)) {
+            const kept = result.tools.filter((tool) => !mask.blocks(tool?.name))
+            if (kept.length !== result.tools.length) result = { ...result, tools: kept }
+          }
+          if (Array.isArray(result.sections)) {
+            let changed = false
+            let present = sdkNames
+            const sections = result.sections.map((section) => {
+              if (section?.name !== SDK_SECTION_NAME || typeof section.text !== 'string') return section
+              const presentNames = () => {
+                present ??= new Set(sdkToolNames(section.text))
+                return present
+              }
+              const names = mask.allow === undefined
+                ? mask.deny
+                : new Set([...presentNames()].filter((name) => mask.blocks(name)))
+              if (names === undefined || names.size === 0) return section
+              const stripped = stripSdkDeclarations(section.text, names)
+              if (stripped === section.text) return section
+              changed = true
+              return { ...section, text: stripped }
+            })
+            if (changed) result = { ...result, sections }
+          }
+        }
+        return result
+      } catch (error) {
+        // 呈现面失败只告警：执行闸已在上面同步过，deny 仍然拦得住。
+        warnOnce(`${plugin}: tool-visibility action ${label} failed, keeping the assembled surface: ${String(error?.message ?? error)}`)
+        return assembled
+      }
+    }))
+  }
+}

package/engine/agent-capability.mjs

@@ -0,0 +1,67 @@
+/**
+ * Agent 级能力声明原语：受众判定 + Agent scope 声明/撤销 + 条件翻转的幂等重挂。
+ *
+ * 只收这三件事。冲突检测与晚到服务等待留给调用方：presentAs 的同 scope 二次声明是
+ * 官方抛错语义，ptcRuntime 的晚到等待是一次性声明；把它们塞进同一接口会逼出模式开关。
+ *
+ * 键是 session：同一个 session 可以换 scope（预设重绑），scope 或能力自己的 key 任一
+ * 变化都先挂新声明、成功后再撤旧的；mount 返回 undefined 表示依赖尚未就绪，保留旧声明、
+ * 下次装配重试（旧闸比无闸安全）。不用 shared.mjs 的 sessionState：闸必须确定性撤销，
+ * 不能按容量淘汰。
+ */
+import { isDelegated } from './shared.mjs'
+
+/** 受众判定：delegationDepth > 0 即子代理（与 shared.mjs 的 isDelegated 同一判据）。 */
+export function capabilityAudience(agent) {
+  return isDelegated(agent?.session) ? 'subagent' : 'main'
+}
+
+/**
+ * 建一个按 Agent 管理的声明表。
+ *
+ * @param mount - `(agent) => { disposers, data? } | undefined`：在 agent.ctx 上声明能力并
+ *   返回撤销器；返回 undefined 表示这次没挂上（依赖未就绪），不记状态、下次 sync 重试。
+ * @returns `{ sync(agent, key), get(session), release(session), releaseAll() }`
+ */
+export function createAgentCapability(mount) {
+  /** session -> { scope, key, disposers, data }；条件翻转或 mask 变化时先撤再挂。 */
+  const states = new Map()
+
+  const release = (session) => {
+    const state = states.get(session)
+    if (state === undefined) return
+    states.delete(session)
+    // 重挂会留下新的 effect 注册；撤销本次的，避免长会话里累积旧 state 闭包。
+    state.effectDispose?.()
+    for (const dispose of state.disposers.splice(0)) {
+      try { dispose() } catch { /* 释放失败不得反过来打断卸载 */ }
+    }
+  }
+  const releaseAll = () => { for (const session of [...states.keys()]) release(session) }
+
+  const sync = (agent, key) => {
+    const session = agent?.session
+    const scope = agent?.ctx
+    if (session === undefined || scope === undefined) return undefined
+    const existing = states.get(session)
+    if (existing !== undefined && existing.scope === scope && existing.key === key) return existing
+    // 依赖未就绪时保留旧闸：先挂新声明，成功后再撤旧的；mount 返回 undefined 直接退出。
+    const mounted = mount(agent)
+    if (mounted === undefined) return existing
+    release(session)
+    const state = { scope, key, disposers: mounted.disposers ?? [], data: mounted.data ?? {}, effectDispose: undefined }
+    states.set(session, state)
+    // 子代理与重绑都换 scope：父 mount 释放必须能撤销，scope 释放只移出自己。
+    if (typeof scope.effect === 'function') {
+      state.effectDispose = scope.effect(() => () => { if (states.get(session) === state) release(session) })
+    }
+    return state
+  }
+
+  return {
+    sync,
+    get: (session) => states.get(session),
+    release,
+    releaseAll,
+  }
+}

package/engine/anchor-match.mjs

@@ -1,22 +1,20 @@
 /**
  * anchor-match — 关键词锚定匹配引擎（纯函数，无状态，无依赖）。
  *
- * 从 strategies 拆解：custom-fallback（自定义锚定词）与 world-book（关键词触发）
+ * 规则条件、锚定词与上下文激活
  * 共用同一套匹配语义——主键/副键、大小写、整词、正则、组合逻辑。
  *
- * 逻辑对齐 ST world_info_logic：
- *   any  = AND_ANY(0)：主键或副键任一命中即激活（world-book 默认 / custom-fallback 单锚）；
- *   all     = AND_ALL(3)：主键命中且副键全部命中；
- *   not     = NOT_ALL(1)：主键命中且副键全部未命中（排除）；
- *   notAny  = NOT_ANY(2)：主键命中且至少一个副键未命中（部分排除）。
+ * 规则条件逻辑：any=主副键任一命中，all=主键命中且副键全中，
+ * not=主键命中且副键全不中，notAny=主键命中且至少一个副键未中。
+ * 上下文激活的具名副键逻辑由候选选择器组合命中数，不借用这些名称。
  *
  * 模式：
- *   scan   = 全文扫描（world-book 消息批匹配）；
+ *   scan   = 全文扫描；
  *   prefix = 文本开头匹配（custom-fallback 首轮 reasoning 锚定确认：确认词集合任一
  *            前缀命中——ASCII 词边界前缀，非 ASCII 直 prefix）。
  */
 
-/** 组合逻辑（ST world_info_logic 映射）。 */
+/** 规则条件的组合逻辑。 */
 export const MATCH_LOGIC = {
   ANY: 'any',
   ALL: 'all',
@@ -29,13 +27,6 @@ export function escapeRegExp(text) {
   return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
 
-/** ST 正则键检测（对齐 world-info.js parseRegexFromString）：
- *  仅 /pattern/flags 显式包裹的键按正则匹配，其余一律字面（含 {{user}} 等
- *  含花括号/正则特殊字符的普通键——ST 不做特殊字符自动检测）。 */
-export function isRegexKey(key) {
-  return parseRegexFromString(key) !== undefined
-}
-
 /** 键 → RegExp（仅 /pattern/flags 形态，模式内未转义 / 分隔符视为非法）；否则 undefined。 */
 export function parseRegexFromString(key) {
   const m = /^\/([\s\S]+?)\/([gimsuy]*)$/u.exec(key)
@@ -51,7 +42,7 @@ export function parseRegexFromString(key) {
 
 /** 单键正则编译（逐键匹配：any/all/not 需要精确的命中键数，捕获组会干扰 match 计数）。
  *  useRegex 三态：true=强制正则；false=强制字面；缺省=ST 语义自动检测。 */
-function compileSingle(key, { caseSensitive, wholeWords, useRegex, stWords }) {
+function compileSingle(key, { caseSensitive, wholeWords, useRegex, wordBoundary }) {
   const flags = caseSensitive ? '' : 'i'
   if (useRegex === true) {
     // ST use_regex=true：键原样作为正则（作者负责合法性）。
@@ -62,7 +53,7 @@ function compileSingle(key, { caseSensitive, wholeWords, useRegex, stWords }) {
     if (auto !== undefined) return auto
   }
   if (wholeWords) {
-    if (stWords) return new RegExp(key.split(/\s+/).length > 1 ? escapeRegExp(key) : `(?:^|\\W)(${escapeRegExp(key)})(?:$|\\W)`, flags)
+    if (wordBoundary === 'ascii-token') return new RegExp(key.split(/\s+/).length > 1 ? escapeRegExp(key) : `(?:^|\\W)(${escapeRegExp(key)})(?:$|\\W)`, flags)
     return new RegExp(`(^|[^\\p{L}\\p{N}])(${escapeRegExp(key)})(?![\\p{L}\\p{N}])`, `${flags}u`)
   }
   return new RegExp(escapeRegExp(key), flags)
@@ -86,7 +77,7 @@ function compileKeyList(list, options) {
  * @param {boolean} [options.useRegex] 三态：true=强制正则 / false=强制字面 / 缺省=自动检测（ST 语义）
  * @param {'any'|'all'|'not'|'notAny'} [options.logic] 组合逻辑（缺省 any）
  * @param {'scan'|'prefix'} [options.mode] 匹配模式（缺省 scan）
- * @param {boolean} [options.stWords] ST 整词规则：多词子串、单词 ASCII 边界；仅 ST 导入开启
+ * @param {'ascii-token'|'unicode'} [options.wordBoundary] 整词边界策略
  * @returns {{ scan: (text: string) => { primary: number, secondary: number, active: boolean } }}
  */
 export function createAnchorMatcher(options = {}) {
@@ -98,10 +89,12 @@ export function createAnchorMatcher(options = {}) {
     useRegex = undefined,
     logic = MATCH_LOGIC.ANY,
     mode = 'scan',
-    stWords = false,
+    wordBoundary = 'unicode',
   } = options
-  const primaryList = compileKeyList(keys, { caseSensitive, wholeWords, useRegex, stWords })
-  const secondaryList = compileKeyList(secondaryKeys, { caseSensitive, wholeWords, useRegex, stWords })
+  if (Object.hasOwn(options, 'stWords')) throw new TypeError('stWords is retired; use wordBoundary')
+  if (!['ascii-token', 'unicode'].includes(wordBoundary)) throw new TypeError('Unknown wordBoundary')
+  const primaryList = compileKeyList(keys, { caseSensitive, wholeWords, useRegex, wordBoundary })
+  const secondaryList = compileKeyList(secondaryKeys, { caseSensitive, wholeWords, useRegex, wordBoundary })
 
   const scan = (raw) => {
     const text = String(raw ?? '')

package/engine/audience.d.mts

@@ -0,0 +1,2 @@
+/** 条件树 → 受众事实的纯模块声明；RuleAudience 的唯一声明处。 */
+export type RuleAudience = 'main' | 'subagent'

package/engine/audience.mjs

@@ -0,0 +1,102 @@
+/**
+ * 条件树 → 受众事实：规则级与动作级受众判据的唯一实现。
+ *
+ * 纯函数，只依赖纯算子清单；不 import `conditions/index.mjs`（那会经 preset 拉入宿主包）。
+ * 返回值 undefined = 无法静态收窄，由调用方按保守方向处理。
+ */
+import { COMPOSITE_OPERATORS } from './conditions/operators.mjs'
+import { record } from './record.mjs'
+
+/** 全部受众；rule-spec 的 action 回退与 audienceInfo 共用这一份。 */
+export const AUDIENCE_ALL = Object.freeze(['main', 'subagent'])
+
+/** 受众成员判据；与 AUDIENCE_ALL 同源，避免各处手写两个字符串比较。 */
+export const isAudience = value => AUDIENCE_ALL.includes(value)
+
+/** 两个受众集合求交；undefined = 无法收窄，取交集时让位于已知集合。 */
+export function intersectAudiences(left, right) {
+  if (left === undefined) return right
+  if (right === undefined) return left
+  return new Set([...left].filter(audience => right.has(audience)))
+}
+
+/** 精确受众集合的补集；只在 not/notAny 的精确子节点上使用。 */
+const complementAudiences = audiences => new Set(AUDIENCE_ALL.filter(audience => !audiences.has(audience)))
+
+/**
+ * 条件树 → 受众上下界；`exact` 表示结果是否能安全取补。
+ *
+ * `all` 求交时跳过无法收窄的子条件：AND 只会更窄，结果仍是「可能命中」的上界，
+ * 但不再精确——此时取补会错误排除受众，所以 `not` / `notAny` 遇非精确子节点返回未知。
+ * `any` 任一分支不精确即整体未知（保守）。
+ */
+function audienceInfo(tree) {
+  if (!record(tree)) return undefined
+  if (record(tree.scope)) {
+    const { audience, modelScope } = tree.scope
+    // 同节点带 pro/flash 时结果还依赖模型，不能取补；缺省与 all 只按受众收窄。
+    if (isAudience(audience)) {
+      return { audiences: new Set([audience]), exact: modelScope === undefined || modelScope === 'all' }
+    }
+  }
+  for (const operator of COMPOSITE_OPERATORS) {
+    const value = tree[operator]
+    if (value === undefined) continue
+    // 非法形状（`all: null` 之类）不猜语义：按无法收窄处理，与重构前的宿主判据一致。
+    if (operator !== 'not' && !Array.isArray(value)) return undefined
+    switch (operator) {
+      case 'all': {
+        let audiences = new Set(AUDIENCE_ALL)
+        let exact = true
+        for (const child of value) {
+          const childInfo = audienceInfo(child)
+          if (childInfo === undefined) {
+            exact = false
+            continue
+          }
+          audiences = intersectAudiences(audiences, childInfo.audiences)
+          if (!childInfo.exact) exact = false
+        }
+        return { audiences, exact }
+      }
+      case 'any': {
+        const audiences = new Set()
+        for (const child of value) {
+          const childInfo = audienceInfo(child)
+          if (childInfo === undefined || !childInfo.exact) return undefined
+          for (const audience of childInfo.audiences) audiences.add(audience)
+        }
+        return { audiences, exact: true }
+      }
+      case 'not': {
+        const childInfo = audienceInfo(value)
+        if (childInfo === undefined || !childInfo.exact) return undefined
+        return { audiences: complementAudiences(childInfo.audiences), exact: true }
+      }
+      case 'notAny': {
+        const childInfo = audienceInfo({ any: value })
+        if (childInfo === undefined || !childInfo.exact) return undefined
+        return { audiences: complementAudiences(childInfo.audiences), exact: true }
+      }
+      default:
+        // 新算子未声明受众语义：不收窄，交给调用方保守处理。
+        return undefined
+    }
+  }
+  return undefined
+}
+
+/**
+ * 条件树 → 受众事实：这条规则可能作用于哪些受众。
+ *
+ * `undefined` = 无法静态收窄，由调用方按保守方向处理。语义与 AND/OR 一致：
+ * - `all` 求交：AND 只会更窄，无法收窄的子条件不扩大结果（结果是上界，不可取补）；
+ * - `any` 保守：任一分支无法收窄，整体就无法排除另一个受众；
+ * - `not` / `notAny` 只对精确子节点取补；`scope.audience` 是唯一能精确收窄的谓词。
+ *
+ * 算子集合来自 `COMPOSITE_OPERATORS`（与 `compileWhen` / `composite` 同源）；
+ * 新增算子若没补受众语义，`test/engine/rule-audiences.test.mjs` 的映射表先红。
+ */
+export function audienceOf(tree) {
+  return audienceInfo(tree)?.audiences
+}

package/engine/branch.d.mts

@@ -0,0 +1,4 @@
+/** `branch.mjs` 的手写声明：只声明 `src/` 消费的导出。 */
+
+/** 分支节点：占动作位、没有 `kind`，但带 `if`/`then`/`else` 之一。 */
+export function isBranchNode(node: unknown): boolean

package/engine/branch.mjs

@@ -1,11 +1,11 @@
 /**
  * 分支语法的唯一展开器：只认 `if`/`then`/`else`，旧名 `when`/`do` 由各入口显式拒绝。
  *
- * 规则（`rule-spec.mjs`）与触发器声明（`trigger-spec.mjs`）共用这一份实现——
- * 两套入口必须是同一套语义，否则同一个模块换个入口就换行为。
+ * 严格版服务规则编译（`rule-spec.mjs`）；宽松版 `expandActionsLenient` 只服务展示投影
+ * （`rule-facts.mjs`），两者共用 `isBranchNode` / `conjunction` 的分支语义。
  */
 
-const record = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+import { record } from './record.mjs'
 
 /** 分支节点：占动作位、没有 `kind`，但带 `if`/`then`/`else` 之一。 */
 export const isBranchNode = node => record(node) && node.kind === undefined
@@ -17,28 +17,71 @@ export function conjunction(conditions) {
   return conditions.length === 1 ? conditions[0] : { all: [...conditions] }
 }
 
+/** 分支两支的 outer 条件：then 追加 if，else 追加 not(if)；缺 if 时保留父条件。 */
+const branchOuters = (node, outer) => ({
+  then: node.if === undefined ? outer : [...outer, node.if],
+  else: node.if === undefined ? outer : [...outer, { not: node.if }],
+})
+
+function walkActions(list, { outer = [], bypass = false, lenient = false, label } = {}) {
+  if (!Array.isArray(list)) {
+    if (!lenient) throw new TypeError(`${label} must be an array`)
+    return []
+  }
+  const out = []
+  for (const [index, node] of list.entries()) {
+    const at = `${label}[${index}]`
+    if (isBranchNode(node)) {
+      if (!lenient) {
+        if (node.if === undefined) throw new TypeError(`${at}: a branch needs if`)
+        if (node.then === undefined) throw new TypeError(`${at}: a branch needs then`)
+      }
+      const { then: thenOuter, else: elseOuter } = branchOuters(node, outer)
+      const thenList = lenient && !Array.isArray(node.then) ? undefined : node.then
+      if (thenList !== undefined) {
+        out.push(...walkActions(thenList, {
+          outer: thenOuter, bypass, lenient,
+          ...(lenient ? {} : { label: `${at}.then` }),
+        }))
+      }
+      const elseList = lenient && !Array.isArray(node.else) ? undefined : node.else
+      if (elseList !== undefined) {
+        out.push(...walkActions(elseList, {
+          outer: elseOuter, bypass, lenient,
+          ...(lenient ? {} : { label: `${at}.else` }),
+        }))
+      }
+      continue
+    }
+    if (lenient) {
+      if (record(node) && typeof node.kind === 'string') out.push({ node, conditions: outer, bypass })
+    } else {
+      out.push({ node, conditions: outer, bypass })
+    }
+  }
+  return out
+}
+
 /**
  * 把一份动作声明展开为扁平的「动作 + 自身分支条件」列表。
  *
  * - 普通动作原样带出，分支条件 = `outer` 的合取（空 = 无条件）；
  * - 分支节点的 `then` 追加本层 `if`、`else` 追加 `not(if)`——互斥由结构保证，不由作者手写；
+ *   有状态谓词（phase / count）还须同时收到 `session/event` 观察（`trigger.mjs` 的
+ *   `wireTriggerObservers`）才成立，否则状态停在冷扫那一刻、互斥也就名存实亡；
  * - 返回顺序即声明序（then 在前、else 在后）；
  * - `bypass` 标记该动作来自**声明级** `else`：它的条件已含 `not(if)`，不能再叠加声明级判定。
  */
 export function expandActions(list, options = {}, label) {
-  if (!Array.isArray(list)) throw new TypeError(`${label} must be an array`)
-  const { outer = [], bypass = false } = options
-  const out = []
-  for (const [index, node] of list.entries()) {
-    const at = `${label}[${index}]`
-    if (isBranchNode(node)) {
-      if (node.if === undefined) throw new TypeError(`${at}: a branch needs if`)
-      if (node.then === undefined) throw new TypeError(`${at}: a branch needs then`)
-      out.push(...expandActions(node.then, { outer: [...outer, node.if], bypass }, `${at}.then`))
-      if (node.else !== undefined) out.push(...expandActions(node.else, { outer: [...outer, { not: node.if }], bypass }, `${at}.else`))
-      continue
-    }
-    out.push({ node, conditions: outer, bypass })
-  }
-  return out
+  return walkActions(list, { ...options, lenient: false, label })
+}
+
+/**
+ * 宽松展开：只服务展示投影（`rule-facts.mjs`）。
+ *
+ * 与 `expandActions` 共享同一条 then/else 遍历，但遇到未完成的分支（缺 `if`/`then`）不抛错：
+ * 有 `then`/`else` 数组就继续下钻；缺 `if` 时两支都按父条件展开（保守，不伪造否定）。
+ */
+export function expandActionsLenient(list, options = {}) {
+  return walkActions(list, { ...options, lenient: true })
 }

package/engine/compaction-epoch.d.mts

@@ -0,0 +1,25 @@
+/** `compaction-epoch.mjs` 的手写声明：只声明 `src/` 消费的导出。 */
+
+/** epoch 感知的晋升相位追踪器；仅覆盖插件依赖面（宿主只把它交给 pre-step 批执行）。 */
+export interface PromotionTracker {
+  /**
+   * 该 agent 当前相位；`boundary` 是最后一次成功压缩的 seq（压缩前为 -1），
+   * `promoted` 表示该边界之后存在 durable 晋升信号。
+   */
+  status(agent?: unknown): { boundary: number; promoted: boolean }
+  /** 增量喂入 `session/event`。 */
+  observe(session: unknown, event: unknown): void
+}
+
+export interface EpochPromotionOptions {
+  includeSubagents?: boolean
+  promoteGate?: boolean
+  promoteAfterFirstResponse?: boolean
+  maxPromoteSteps?: number
+  reasoningPattern?: string
+  reasoningNegativePattern?: string
+  reasoningFlags?: string
+}
+
+/** 建一份相位追踪器；`promoteEvents` 是 durable 事件类型集合（见 `shared.mjs#PROMOTE_EVENTS`）。 */
+export function createEpochPromotion(promoteEvents: Iterable<string>, options?: EpochPromotionOptions): PromotionTracker