dsh-plugin-prompt-tool 2.0.1 → 3.0.0

package/engine/machine-paths.mjs

@@ -0,0 +1,40 @@
+/**
+ * 机器路径事实的**唯一取值来源**：`DSH_HOME` / `CWD` / `WORKSPACE` 三个键怎么推导，只在这里定。
+ *
+ * 此前这条配方在四处各写一遍——`interpolate` 的内置变量、`fillers` 的 env facts、
+ * `run-code-env` 的进程环境兜底、`instruction-hint` 的指令文件探测——而且已经分叉：
+ * 未设 `DSH_HOME` 时前两者按用户主目录推导出 `<USERPROFILE>\.dsh`，`run-code-env` 则
+ * **不给该键**。同一台机器上 `{{DSH_HOME}}` 与 `run_code` 里的 `env.DSH_HOME` 因此可能
+ * 是两个答案。
+ *
+ * 本模块只提供**取值**：各处的白名单、注入形态（插值保留名 / variables / 进程 env）与
+ * 「空值算不算有值」的策略留在调用方——它们的产出物本来就不同，不该被这一个函数接管。
+ */
+
+/**
+ * @param {object|undefined} session 会话（读它的 `header.cwd`；缺省回退进程 cwd）
+ * @param {Record<string, string|undefined>|undefined} env 环境来源（缺省取当前 `process.env`；
+ *   宿主快照与测试可显式替换——测试**应该**传它，否则读真实环境、用例不稳定）
+ * @returns {{ DSH_HOME: string, WORKSPACE: string, CWD: string }}
+ *   `DSH_HOME`：显式环境变量 → `<USERPROFILE>\.dsh` → 空串（**不是** `undefined`：
+ *   调用方若要区分「不可用」，自行把空串当缺省——例如 `instruction-hint` 需要
+ *   `undefined` 表示「没有可探测的全局目录」）。
+ *
+ * **只给取值，不给策略**：键要不要出现在产物里由调用方决定。例如 `run-code-env` 原来
+ * 「没有会话 cwd 就不写 `DSH_WORKSPACE`」，统一取值后 `CWD` 会回退到 `process.cwd()`，
+ * 那处仍按自己的规则判空后再决定是否落键。
+ *
+ * 无 `process` 的环境（非 Node 宿主）不抛：环境与 cwd 都退化成空值，与 `run-code-env`
+ * 原来的 `typeof process === 'undefined'` 守卫同口径。
+ */
+export function machinePaths(session, env = currentEnv()) {
+  const cwd = session?.header?.cwd ?? currentCwd()
+  return {
+    DSH_HOME: env?.DSH_HOME ?? (env?.USERPROFILE ? `${env.USERPROFILE}\\.dsh` : ''),
+    WORKSPACE: env?.DSH_WORKSPACE ?? cwd,
+    CWD: cwd,
+  }
+}
+
+const currentEnv = () => (typeof process === 'undefined' ? undefined : process.env)
+const currentCwd = () => (typeof process === 'undefined' ? '' : process.cwd())

package/engine/module-file-tools.mjs

@@ -0,0 +1,8 @@
+import { toolServiceName } from './service-names.mjs'
+
+export const name = 'module-file-tools'
+export function apply(ctx) {
+  ctx.inject([toolServiceName('module-file-tools')], scopeCtx => {
+    scopeCtx.effect(() => scopeCtx.get(toolServiceName('module-file-tools')).mount(scopeCtx), name + ': mount')
+  })
+}

package/engine/module-import-tools.mjs

@@ -0,0 +1,10 @@
+/** 角色卡库工具预设模块。 */
+import { toolServiceName } from "./service-names.mjs"
+
+export const name = "module-import-tools"
+
+export function apply(ctx) {
+  ctx.inject([toolServiceName("module-import-tools")], (scopeCtx) => {
+    scopeCtx.effect(() => scopeCtx.get(toolServiceName("module-import-tools")).mount(scopeCtx), name + ": mount")
+  })
+}

package/engine/module-manifest-tools.mjs

@@ -0,0 +1,8 @@
+import { toolServiceName } from './service-names.mjs'
+
+export const name = 'module-manifest-tools'
+export function apply(ctx) {
+  ctx.inject([toolServiceName('module-manifest-tools')], scopeCtx => {
+    scopeCtx.effect(() => scopeCtx.get(toolServiceName('module-manifest-tools')).mount(scopeCtx), name + ': mount')
+  })
+}

package/engine/module-rule-tools.mjs

@@ -0,0 +1,10 @@
+/** 完整模块规则工具，按声明等待宿主 provider。 */
+import { toolServiceName } from './service-names.mjs'
+
+export const name = 'module-rule-tools'
+
+export function apply(ctx) {
+  ctx.inject([toolServiceName('module-rule-tools')], scopeCtx => {
+    scopeCtx.effect(() => scopeCtx.get(toolServiceName('module-rule-tools')).mount(scopeCtx), name + ': mount')
+  })
+}

package/engine/module-variable-tools.mjs

@@ -0,0 +1,10 @@
+/** 两级持久模块变量工具，按声明等待宿主 provider。 */
+import { toolServiceName } from './service-names.mjs'
+
+export const name = 'module-variable-tools'
+
+export function apply(ctx) {
+  ctx.inject([toolServiceName('module-variable-tools')], scopeCtx => {
+    scopeCtx.effect(() => scopeCtx.get(toolServiceName('module-variable-tools')).mount(scopeCtx), name + ': mount')
+  })
+}

package/engine/order.d.mts

@@ -0,0 +1,14 @@
+/** `order.mjs` 的手写声明：只声明 `src/` 消费的导出。 */
+
+/** 排序所需的身份字段；仅覆盖插件依赖面（其余字段引擎不读）。 */
+export interface ConfigSequenceLike {
+  id: string
+  sequence?: number
+  order?: number
+  sourceModuleId?: string
+  ruleId?: string
+  ruleActionIndex?: number
+}
+
+/** 模块配置的执行顺序：`sequence`（回退 `order`）优先，其次模块与规则身份。 */
+export function compareConfigSequence(a: ConfigSequenceLike, b: ConfigSequenceLike): number

package/engine/order.mjs

@@ -1,6 +1,3 @@
-/** 加载器私有元数据：不进入 YAML、公共配置或客户端载荷。 */
-export const FILE_SEQUENCE = Symbol('prompt-tool:file-sequence')
-
 const compareText = (a, b) => a < b ? -1 : a > b ? 1 : 0
 
 /** 模块配置按持久序号执行；无物化来源的独立调用保留原 order 语义。 */

package/engine/path-safety.d.mts

@@ -0,0 +1,2 @@
+/** `path-safety.mjs` 的手写声明：只声明 `src/` 消费的导出。 */
+export function resolveRealWithin(target: string, roots: readonly string[], label?: string): string

package/engine/path-safety.mjs

@@ -0,0 +1,58 @@
+/**
+ * path-safety — 真实路径（realpath）边界：词法 containment 拦不住 symlink / junction。
+ *
+ * 两个消费者共用这一条判据：instruction-hint 读 params.file、tool-config-engine 的 fs 执行器。
+ * 已存在的目标解析自身；新文件解析父目录（writeFileSync 不创建目录），悬空链接先按
+ * readlink 追到缺失目标——否则 write 会顺着链接写到信任根之外。
+ */
+
+import { readlinkSync, realpathSync } from 'node:fs'
+import { basename, dirname, join, resolve, sep } from 'node:path'
+
+/** target 在 root 内（含 root 自身）；两者都必须是真实路径。 */
+function isWithin(root, target) {
+  if (target === root) return true
+  return target.startsWith(root.endsWith(sep) ? root : root + sep)
+}
+
+/** 目标真实路径；深层目录不存在或链接环时抛出原始错误。 */
+function realPathOf(target) {
+  try {
+    return realpathSync(target)
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error
+    let link
+    try { link = readlinkSync(target) } catch { link = undefined }
+    // 悬空符号链接：realpath 看不到目标，但 write 会顺着它落盘，所以先解析链接本身。
+    if (link !== undefined) return realPathOf(resolve(dirname(target), link))
+    return join(realpathSync(dirname(target)), basename(target))
+  }
+}
+
+/** 信任根的真实路径；不存在或不可解析的根跳过——根不可用不等于放行。 */
+function usableRoots(roots) {
+  const allowed = []
+  for (const root of roots) {
+    if (typeof root !== 'string' || root.length === 0) continue
+    try { allowed.push(realpathSync(root)) } catch { /* 根不存在或不可解析 */ }
+  }
+  return allowed
+}
+
+/**
+ * 解析 target 并要求真实路径落在任一信任根内（fail closed）。
+ *
+ * @param target 已 resolve 的绝对路径（相对路径由调用方按自己的基目录解析）
+ * @param roots 信任根：会话 cwd、DSH_HOME 等
+ * @param label 报错中的对象名（path / instruction file）
+ * @returns 真实路径：调用方后续 IO 都用它，避免校验与使用之间再次经过链接
+ */
+export function resolveRealWithin(target, roots, label = 'path') {
+  const real = realPathOf(target)
+  const allowed = usableRoots(roots)
+  if (allowed.some((root) => isWithin(root, real))) return real
+  const shown = allowed.length > 0
+    ? allowed.join(', ')
+    : roots.filter((root) => typeof root === 'string' && root.length > 0).join(', ') || 'the trust roots'
+  throw new Error(`${label} ${JSON.stringify(target)} escapes the trust root: real path ${JSON.stringify(real)} is outside ${shown}`)
+}

package/engine/pre-step-source.d.mts

@@ -0,0 +1,69 @@
+/** `pre-step-source.mjs` 的手写声明：来源形状与批合并的唯一权威。 */
+import type { PromotionTracker } from './compaction-epoch.mjs'
+
+/** pre-step 条目；只声明调度/批执行读取的字段。 */
+export interface PreStepConfigLike {
+  id: string
+  layer?: string
+  position?: string
+  promotion?: string
+  audience?: string | null
+  modelScope?: string
+  dedupe?: string
+  texts?: string[]
+  params?: Record<string, unknown>
+  variables?: Record<string, unknown>
+  sequence?: number
+  order?: number
+  sourceModuleId?: string
+  /** 规则实例；批执行器据此把判定上报分给来源。 */
+  rule?: unknown
+  /** 由来源生产者绑定 ctx 的逐条求值事务。 */
+  resolve?(input: Record<string, unknown>): unknown
+}
+
+/** 来源侧判定上报；moduleId 等归属由 source 自己闭包，不在此重复。 */
+export interface PreStepOutcomeReport {
+  ruleId: string
+  channel: string
+  outcome: string
+}
+
+export type PreStepOutcomeSink = (report: PreStepOutcomeReport) => void
+
+/** 执行 owner 唯一持有的晋升实例对；source 只携带同一引用。 */
+export interface PreStepPromotion {
+  main: PromotionTracker
+  withSubagents: PromotionTracker
+}
+
+/** 一次 pre-step 注册；ctx/onOutcome/promotion 都是来源事实。 */
+export interface PreStepSource {
+  sourceId: string
+  configs: readonly PreStepConfigLike[]
+  ruleActions?: readonly unknown[]
+  ctx: unknown
+  onOutcome?: PreStepOutcomeSink
+  promotion?: PreStepPromotion
+}
+
+export interface CreatePreStepSourceOptions {
+  sourceId: string
+  configs: readonly PreStepConfigLike[]
+  ruleActions?: readonly unknown[]
+  ctx: unknown
+  onOutcome?: PreStepOutcomeSink
+  promotion?: PreStepPromotion
+}
+
+/** 批执行所需的扁平事实；report 是三参内部适配器（来源 onOutcome 是对象 sink）。 */
+export interface ComposedPreStepSources {
+  configs: PreStepConfigLike[]
+  ruleActions: unknown[]
+  promotion?: PreStepPromotion
+  report?: (rule: { id: string }, channel: string, outcome: string) => void
+}
+
+export function createPreStepSource(options: CreatePreStepSourceOptions): PreStepSource
+export function promotionOwnerOf(sources: ReadonlyArray<PreStepSource>): PreStepPromotion | undefined
+export function composePreStepSources(sources: ReadonlyArray<PreStepSource>): ComposedPreStepSources

package/engine/pre-step-source.mjs

@@ -0,0 +1,103 @@
+/**
+ * pre-step-source — 一次 pre-step 注册所携带的事实。
+ *
+ * 来源生产者（mountRuleSources / 直接 inject-text）在这里绑定自己的 ctx；执行 owner
+ * （coordinator 或独立 apply）只合并来源、检查 promotion 唯一性，并按 rule 分派判定上报。
+ * 本模块不做注入、不排序、不读会话。
+ */
+
+/** 来源身份前缀的唯一出处；调用方不要再手写 `module:` / `preset:`。 */
+export const moduleSourceId = moduleId => `module:${moduleId}`
+export const presetSourceId = id => `preset:${id}`
+
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+/** 来源 ctx 绑定一次；批执行传入的 ctx 不覆盖来源自己的 scope。 */
+export function createPreStepSource(options) {
+  if (!isRecord(options)) throw new TypeError('pre-step source options must be an object')
+  const { sourceId, configs, ruleActions, ctx, onOutcome, promotion } = options
+  if (typeof sourceId !== 'string' || sourceId.length === 0) {
+    throw new TypeError('pre-step source requires a non-empty sourceId')
+  }
+  if (ctx === undefined || ctx === null) throw new TypeError(`pre-step source ${sourceId} requires a ctx`)
+  if (!Array.isArray(configs)) throw new TypeError(`pre-step source ${sourceId}.configs must be an array`)
+  if (ruleActions !== undefined && !Array.isArray(ruleActions)) {
+    throw new TypeError(`pre-step source ${sourceId}.ruleActions must be an array when present`)
+  }
+  if (onOutcome !== undefined && typeof onOutcome !== 'function') {
+    throw new TypeError(`pre-step source ${sourceId}.onOutcome must be a function when present`)
+  }
+  if (promotion !== undefined && (!isRecord(promotion) || !isRecord(promotion.main) || !isRecord(promotion.withSubagents))) {
+    throw new TypeError(`pre-step source ${sourceId}.promotion must be a { main, withSubagents } pair when present`)
+  }
+  const bound = configs.map((config, index) => {
+    if (!isRecord(config)) throw new TypeError(`pre-step source ${sourceId}.configs[${index}] must be an object`)
+    const resolve = config.resolve
+    return {
+      ...config,
+      ...(typeof resolve !== 'function' ? {} : {
+        resolve: input => resolve({ ...input, ctx }),
+      }),
+    }
+  })
+  return {
+    sourceId,
+    configs: bound,
+    ...(ruleActions === undefined ? {} : { ruleActions: [...ruleActions] }),
+    ctx,
+    ...(onOutcome === undefined ? {} : { onOutcome }),
+    ...(promotion === undefined ? {} : { promotion }),
+  }
+}
+
+/** 所有有 owner 的来源必须引用同一个实例；返回该 owner（没有则 undefined）。 */
+export function promotionOwnerOf(sources) {
+  const owners = sources.map(source => source.promotion).filter(owner => owner !== undefined)
+  if (owners.length > 1 && owners.some(owner => owner !== owners[0])) {
+    throw new TypeError('pre-step sources must share one promotion owner')
+  }
+  return owners[0]
+}
+
+/**
+ * 合并来源，建立唯一的 promotion owner 与按 rule 分派的判定上报。
+ * 有实际工作（configs/ruleActions 非空）却没有 promotion，或 owner 不一致，都 fail loud。
+ */
+export function composePreStepSources(sources) {
+  if (!Array.isArray(sources)) throw new TypeError('pre-step sources must be an array')
+  if (sources.length === 0) return { configs: [], ruleActions: [] }
+  for (const source of sources) {
+    if (!isRecord(source) || typeof source.sourceId !== 'string' || !Array.isArray(source.configs)) {
+      throw new TypeError('pre-step sources must be objects created by createPreStepSource')
+    }
+  }
+  const configs = sources.flatMap(source => source.configs)
+  const ruleActions = sources.flatMap(source => source.ruleActions ?? [])
+  const hasWork = configs.length > 0 || ruleActions.length > 0
+  const promotion = promotionOwnerOf(sources)
+  if (hasWork && promotion === undefined) {
+    throw new TypeError('pre-step sources need one promotion owner before batch execution')
+  }
+  // rule → source sink；只保留首个来源，避免同一条规则被来源重复声明时重复记账。
+  const sinks = new Map()
+  const collect = (entry, sink) => {
+    if (!isRecord(entry) || !isRecord(entry.rule) || typeof sink !== 'function' || sinks.has(entry.rule)) return
+    sinks.set(entry.rule, sink)
+  }
+  for (const source of sources) {
+    for (const config of source.configs) collect(config, source.onOutcome)
+    for (const action of source.ruleActions ?? []) collect(action, source.onOutcome)
+  }
+  const report = sinks.size === 0
+    ? undefined
+    : (rule, channel, outcome) => {
+      const sink = sinks.get(rule)
+      if (sink !== undefined) sink({ ruleId: rule.id, channel, outcome })
+    }
+  return {
+    configs,
+    ruleActions,
+    ...(promotion === undefined ? {} : { promotion }),
+    ...(report === undefined ? {} : { report }),
+  }
+}

package/engine/present-as.mjs

@@ -0,0 +1,77 @@
+/**
+ * present-as — 声明**本模块覆盖的 Agent** 以哪种形态呈现工具（官方 `ctx.tools.presentAs`）。
+ *
+ * 为什么需要它：官方 PTC 呈现由 `@deepseek-ai/dsh-agent-tool-presentation` 行声明，而那是
+ * **预设侧**的装配（preset 的常驻 scope）。本插件的模块行挂载在 **Agent scope**
+ * （`src/runtime/agent-assembly.ts` 的 `agent.ctx.plugin(...)` → `module.apply(scopeCtx, …)`），
+ * 拿到的正是 `presentAs` 要求的 scoped ctx——所以模块可以直接声明呈现，不必在预设里再挂
+ * 官方行，也不必动 `cordis.patch.yml`（那条只用于**进程级默认**呈现，见下）。
+ *
+ * 与官方行的关系：调的是同一个 `presentAs`，语义等价；差别在 scope——本行落在 Agent scope
+ * （更近），`modeFor` 沿 scope 链**最近者优先**，所以它与预设里的官方行可以并存。但**同一
+ * scope 二次声明会被官方拒绝**（挂载期抛错 `tools.presentAs("x") conflicts with "y" already
+ * declared for this scope`）——本行不捕获、不降级，让它响亮失败（装配失败优于静默换形态）。
+ *
+ * `ptc` 需要 `ctx.ptcRuntime`（宿主 base bundle 的 `ptc-runtime` 行提供）：用 `ctx.inject`
+ * 等它就绪再声明；等不到本行停在 pending，由预设注册表指名报告**不可用的行**——刻意不静默
+ * 退回 native，否则「开了 PTC」的部署会悄悄以 native 跑。`native` 不需要运行时，直接声明。
+ *
+ * disposer：`presentAs` 本身就是 effect（它用调用方的 ctx 注册、并把那个 disposer 还回来），
+ * 本行不再包一层，随 fiber 释放即撤销。
+ *
+ * 进程级默认呈现不走本行：那要改宿主 `tools` 行的 `config.mode`（部署选择）。
+ */
+
+import { bool, defineConfig, enumOf } from './fields.mjs'
+import { capabilityAudience } from './agent-capability.mjs'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'present-as'
+
+/**
+ * 呈现声明走 `ctx.tools`。
+ * `ptcRuntime` **刻意不进 inject**（官方同一取舍）：那样会让 `native` 行也被绑死在
+ * 「部署里必须有 PTC 运行时」上，而它与运行时毫无关系。
+ */
+export const inject = ['tools']
+
+/**
+ * 配置契约：字段声明是白名单（未知键 = 打字错误）与逐字段归一化的单一来源
+ * （导出供契约对拍测试使用）。`enabled` 未声明 = 关闭，组合源显式写 `enabled: true`。
+ */
+export const configContract = defineConfig({
+  enabled: bool({ default: false }),
+  mode: enumOf(['native', 'ptc'], { required: true }),
+  mainMode: enumOf(['native', 'ptc']),
+  subagentMode: enumOf(['native', 'ptc']),
+})
+
+/**
+ * 把本 scope 的工具呈现声明成 `config.mode`。
+ *
+ * @param ctx - 本模块行的挂载作用域（Agent scope）上下文。
+ * @param config - `mode` 为必填兼容默认；主/子覆盖独立、缺省继承 mode。
+ * @param options - 配装方持有的 Agent；不从 Context 猜测会话身份。
+ */
+export function apply(ctx, config, { agent } = {}) {
+  // 校验入口：未知键 / enabled 非布尔 / mode 缺失或不在枚举内一律挂载期 fail loud。
+  const source = configContract.parse(config, name)
+  if (!source.enabled) return
+  const mode = (capabilityAudience(agent) === 'subagent' ? source.subagentMode : source.mainMode) ?? source.mode
+  if (mode === 'native') {
+    ctx.tools.presentAs('native')
+    return
+  }
+  // ptcRuntime 晚到也继续等待；缺失时先告警，避免“ptc 已启用却按 native 跑”没有任何痕迹。
+  let warnedPending = false
+  if (typeof ctx.get === 'function' && ctx.get('ptcRuntime') === undefined) {
+    warnedPending = true
+    try { ctx.logger?.warn?.('present-as: ptcRuntime 尚未就绪；本行保持 pending，不会声明 native；若宿主始终不提供，装配停在未呈现状态') } catch { /* logger 不可用不阻断装配 */ }
+  }
+  ctx.inject(['ptcRuntime'], (runtimeCtx) => {
+    if (warnedPending) {
+      try { ctx.logger?.info?.('present-as: ptcRuntime 已就绪，声明 ptc') } catch { /* logger 不可用不阻断装配 */ }
+    }
+    runtimeCtx.tools.presentAs('ptc')
+  })
+}

package/engine/promotion-pool.d.mts

@@ -0,0 +1,9 @@
+/** `promotion-pool.mjs` 的手写声明：池按配置复用并统一喂事件。 */
+import type { PromotionTracker } from './compaction-epoch.mjs'
+
+export interface PromotionPool {
+  tracker(promoteEvents: readonly string[], options?: Record<string, unknown>): PromotionTracker
+  dispose(): void
+}
+
+export function createPromotionPool(ctx: unknown): PromotionPool

package/engine/promotion-pool.mjs

@@ -0,0 +1,69 @@
+/**
+ * 晋升相位追踪器池：同一挂载内按配置复用追踪器，事件由池**统一喂**。
+ *
+ * 为什么需要池：`createEpochPromotion` 自己不订阅任何事件（它的 ctx 参数完全用不到，
+ * 见 `compaction-epoch.mjs` 的条目容器注释），初始相位靠 `status()` 触发的**全量冷扫**建立。
+ * 此前 `executor` 每次 pre-step apply 建两份、`phase` 每个编译谓词建一份、
+ * `instruction-hint` 每次 apply 建一份，各自订阅、各自喂——重复建的代价就是重复冷扫。
+ *
+ * **池自己订阅**：订阅随池的归属走（自建池随所在挂载释放，注入池由创建者释放），
+ * 调用方不需要记住「注入时谁来喂事件」——忘了就是相位停在冷扫那一刻的静默失效。
+ *
+ * 状态仍按 `session.id` 分条（追踪器内部的 `sessionState`）：池只合并**实例与订阅**，
+ * 不共享会话状态，也不改变「状态是快路径、真相在事件流」这条纪律。
+ */
+import { createEpochPromotion } from './compaction-epoch.mjs'
+
+/**
+ * 进缓存的选项键：**任何影响判定的配置都必须登记**，否则同 key 会掩盖不同行为。
+ * 与 `createEpochPromotion` 读取的选项一一对应。
+ */
+const KEYED_OPTIONS = [
+  'includeSubagents',
+  'promoteGate',
+  'promoteAfterFirstResponse',
+  'reasoningPattern',
+  'reasoningNegativePattern',
+  'reasoningFlags',
+  'maxPromoteSteps',
+]
+
+const trackKey = (promoteEvents, options) => JSON.stringify([
+  // 追踪器内部是 `new Set(promoteEvents)`：声明顺序无判定语义，不排序会把同一配置缓存成两份。
+  [...promoteEvents].sort(),
+  // 固定键序，避免书写顺序造成同配置两份。
+  KEYED_OPTIONS.map(key => [key, options[key]]),
+])
+
+/**
+ * @param {object} ctx 归属上下文（`ctx.on` 用来订阅 `session/event`）
+ * @returns {{ tracker: (promoteEvents: readonly string[], options?: object) => object, dispose: () => void }}
+ */
+export function createPromotionPool(ctx) {
+  const trackers = new Map()
+  let disposed = false
+  // 喂给池内所有实例：追踪器对未 scan 的会话本身是 no-op（首次 `status()` 会全量重建），
+  // 因此统一喂不会把状态喂给还没建立相位的会话。
+  const release = ctx.on('session/event', (session, event) => {
+    for (const tracker of trackers.values()) tracker.observe(session, event)
+  })
+  return {
+    /** 按配置取追踪器：同配置复用、异配置分建（配置不同就是不同的相位语义）。 */
+    tracker(promoteEvents, options = {}) {
+      const key = trackKey(promoteEvents, options)
+      let tracker = trackers.get(key)
+      if (tracker === undefined) {
+        tracker = createEpochPromotion(promoteEvents, options)
+        trackers.set(key, tracker)
+      }
+      return tracker
+    },
+    /** 释放订阅并丢弃实例；追踪器本身没有 disposer（状态随闭包回收）。 */
+    dispose() {
+      if (disposed) return
+      disposed = true
+      trackers.clear()
+      release?.()
+    },
+  }
+}

package/engine/record.mjs

@@ -0,0 +1,2 @@
+/** 统一的对象形状判据；纯 ESM，无宿主 import，供引擎内多个纯模块共用。 */
+export const record = value => value !== null && typeof value === 'object' && !Array.isArray(value)

package/engine/rule-engine.mjs

@@ -35,6 +35,7 @@ export async function apply(ctx, config) {
     : isAbsolute(source.moduleRoot) ? pathToFileURL(source.moduleRoot.replace(/[\\/]?$/, '/')) : new URL(source.moduleRoot.replace(/\/?$/, '/'), templateBaseUrl)
   const strategyDir = source.strategyDir === undefined ? undefined : isAbsolute(source.strategyDir) ? pathToFileURL(source.strategyDir).href : new URL(source.strategyDir, templateBaseUrl).href
   const moduleId = typeof packet.moduleId === 'string' ? packet.moduleId : basename(dirname(file))
-  const rules = compileRules(packet.rules, { moduleId, variables: packet.variables, variablesEnabled: packet.variablesEnabled, configOrder: packet.configOrder, ctx, standingMountFor: await loadStandingMountFor(), promptConfigOptions: { templateBaseUrl, templateModuleRoot, strategyDir } })
-  return mountRuleSources(ctx, [{ moduleId, rules }])
+  const rules = compileRules(packet.rules, { moduleId, variables: packet.variables, variablesEnabled: packet.variablesEnabled, configOrder: packet.configOrder, promptConfigOptions: { templateBaseUrl, templateModuleRoot, strategyDir } })
+  // 条件在挂载缝绑定（preset 需要挂载 scope 的 ctx）；官方模块导出只作可选兜底。
+  return mountRuleSources(ctx, [{ moduleId, rules }], { standingMountFor: await loadStandingMountFor() })
 }

package/engine/rule-facts.d.mts

@@ -0,0 +1,11 @@
+/** `rule-facts.mjs` 的客户端消费面；形状按实现写实。 */
+import type { RuleAudience } from './audience.mjs'
+export type { RuleAudience }
+
+export interface RuleFacts {
+  /** 可能受众的上界；undefined = 无法静态收窄，调用方按两个受众处理。 */
+  audiences: Set<RuleAudience> | undefined
+  /** 是否包含 canonical context-activation 的 inject-text 动作。 */
+  contextActivation: boolean
+}
+export function ruleFacts(rule: unknown): RuleFacts

package/engine/rule-facts.mjs

@@ -0,0 +1,60 @@
+/**
+ * raw rule 的规则事实（只读）：可能受众 + 是否包含 context activation。
+ *
+ * 只服务 UI/消费者，不参与执行、不替代 `rule-spec` 的编译与 `audienceOf` 的运行时判据。
+ * 纯 ESM，无宿主 import；与 `expandActions` 同构地展开 then/else/嵌套分支，但不编译动作。
+ */
+import { audienceOf, intersectAudiences, isAudience } from './audience.mjs'
+import { conjunction, expandActionsLenient } from './branch.mjs'
+import { isFixedRegistration } from './fixed-registration.mjs'
+import { record } from './record.mjs'
+import { CONTEXT_ACTIVATION_STRATEGY } from './strategy-ids.mjs'
+
+function targetAudiences(action, ruleLayer) {
+  // 文档只允许固定 system-section 的 registration target 用 config.audience 收窄；
+  // 与引擎共用 isFixedRegistration（含 config.layer ?? rule.layer 回退）。
+  if (action.kind !== 'inject-text') return undefined
+  const config = record(action.config) ? action.config : undefined
+  if (!isFixedRegistration(config, ruleLayer)) return undefined
+  const raw = config.audience
+  return isAudience(raw) ? new Set([raw]) : undefined
+}
+
+function hasContextActivation(expanded) {
+  return expanded.some(({ node }) => node.kind === 'inject-text'
+    && record(node.config)
+    && node.config.strategy === CONTEXT_ACTIVATION_STRATEGY)
+}
+
+/**
+ * 一条 raw rule 的规则事实。
+ *
+ * `audiences` 是 then/else/嵌套分支动作可能受众的并集；任一动作无法收窄则整体
+ * `undefined`（调用方按两个受众处理）。没有动作时回退到规则级 `if`，让正在编辑的
+ * 空卡仍按它的受众条件过滤。`contextActivation` 只识别 `inject-text` 且 strategy
+ * 为 canonical context-activation 的动作，不执行选择或注入。
+ */
+export function ruleFacts(rule) {
+  if (!record(rule)) return { audiences: undefined, contextActivation: false }
+  const expanded = [
+    ...expandActionsLenient(rule.then, { bypass: false }),
+    ...expandActionsLenient(rule.else, {
+      outer: rule.if === undefined ? [] : [{ not: rule.if }],
+      bypass: true,
+    }),
+  ]
+  const when = audienceOf(rule.if)
+  if (expanded.length === 0) return { audiences: when, contextActivation: false }
+  let audiences
+  for (const { node, conditions, bypass } of expanded) {
+    const conditioned = intersectAudiences(bypass ? undefined : when, audienceOf(conjunction(conditions)))
+    const effective = intersectAudiences(conditioned, targetAudiences(node, rule.layer))
+    if (effective === undefined) {
+      audiences = undefined
+      break
+    }
+    audiences ??= new Set()
+    for (const audience of effective) audiences.add(audience)
+  }
+  return { audiences, contextActivation: hasContextActivation(expanded) }
+}

package/engine/rule-runtime.d.mts

@@ -0,0 +1,46 @@
+/** `rule-runtime.mjs` 的手写声明：只声明 `src/` 消费的导出。 */
+import type { StandingMountFor } from './conditions/index.mjs'
+import type { PromotionPool } from './promotion-pool.mjs'
+import type { PreStepPromotion } from './pre-step-source.mjs'
+import type { WarnOnce } from './shared.mjs'
+
+/** 变量读写通道（插件侧的模块变量适配器）；引擎只按这三个方法调用。 */
+export interface RuleVariableStore {
+  read(moduleId: string): unknown
+  commit(moduleId: string, request: unknown): unknown
+  publish(moduleId: string): void
+}
+
+/** 判定上报载荷；仅覆盖插件依赖面（宿主按 `RuleOutcomeReport` 消费它）。 */
+export interface RuleOutcomeReport {
+  moduleId?: string
+  ruleId: string
+  channel: string
+  outcome: string
+}
+
+/** 一次挂载的规则来源；规则对象是 `rule-spec.mjs#compileRules` 的产物。 */
+export interface RuleSourceLike {
+  moduleId: string
+  rules: readonly unknown[]
+}
+
+export interface MountRuleSourcesOptions {
+  agent?: unknown
+  plugin?: string
+  warnOnce?: WarnOnce
+  variableStore?: RuleVariableStore
+  /** 官方预设兜底；缺省＝没有兜底（预设条件恒不命中）。 */
+  standingMountFor?: StandingMountFor
+  /** 注入的晋升相位实例对；缺省从协调器或自建池取。 */
+  promotion?: PreStepPromotion
+  promotionPool?: PromotionPool
+  onOutcome?(report: RuleOutcomeReport): void
+}
+
+/** 所有规则来源的唯一装配入口；返回释放本次挂载的 disposer。 */
+export function mountRuleSources(
+  ctx: unknown,
+  sources: ReadonlyArray<RuleSourceLike>,
+  options?: MountRuleSourcesOptions,
+): () => void