@xiciyang/rsi-contract 0.0.0-stage → 0.1.0

package/src/goal-setting.mjs

@@ -0,0 +1,255 @@
+/**
+ * goal-setting.mjs —— 能力 ①「目标设定」。
+ *
+ * 输入：系统状态（当前度量 / 血缘 / 既往轮次）。
+ * 输出：**排序后的候选改进目标**（每条自带证据引用、期望增量、阻断原因）。
+ *
+ * ─────────────────────────── 三条硬纪律 ───────────────────────────
+ *
+ * ① **绝不发明度量**。`state.metrics` 缺失或为空 ⇒ `refused: true` + `goals: []`。
+ *    不做"按历史猜一个当前值"这种事 —— 那正是产物带假证据的入口。
+ *
+ * ② **期望增量必须有来源**。只接受两种来源，二者都要能在输入内复核：
+ *      (a) 度量自带 `expectedDelta`（并要求该度量带可解析的 `evidenceRefs`）；
+ *      (b) 既往轮次的实测 `delta` 的**中位数**（证据引用=那些轮次 id）。
+ *    两者都没有 ⇒ 该候选 `blocked: E_GOAL_MEANINGLESS`。
+ *    中位数而不是均值：均值会被单次异常轮次拉动，而"用哪一版统计量"必须写死在代码里。
+ *
+ * ③ **冲突不替调用方选边**。已声明的 tradeoff / mutually-exclusive 关系里的**双方**都 blocked，
+ *    并互相点名（`conflictsWith`）。静默挑一个"更优的"就是把一个已知冲突藏起来。
+ *
+ * 排序是**全序**（blocked 在后 → priority 降序 → goalId 升序），故输出顺序与输入顺序无关。
+ */
+
+import { CAPABILITY_VERSION } from './version.mjs'
+import {
+  assertPlainObject, assertArray, optionalArray, finiteNumber, nonEmptyString, directionOf,
+  median, uniqSorted, RsiLoopError,
+} from './support.mjs'
+
+export const CAPABILITY_ID = 'goalSetting'
+
+export function goalSetting(input) {
+  const arg = assertPlainObject(input ?? {}, 'goalSetting 入参', 'E_INPUT_SHAPE')
+  const state = assertPlainObject(arg.state ?? null, 'state', 'E_INPUT_SHAPE')
+  const metrics = state.metrics
+
+  // ── ① fail-closed：没有度量就没有目标 ──
+  if (metrics === undefined || metrics === null || (typeof metrics === 'object' && Object.keys(metrics).length === 0)) {
+    return {
+      capability: CAPABILITY_ID,
+      version: CAPABILITY_VERSION,
+      goals: [],
+      refused: true,
+      code: 'E_METRICS_ABSENT',
+      reasons: ['state.metrics 缺失或为空 ⇒ 不产出任何目标（本库不发明度量：兜底默认值必须 fail-closed）'],
+      evidenceRefs: [],
+    }
+  }
+  assertPlainObject(metrics, 'state.metrics', 'E_INPUT_SHAPE')
+
+  const history = optionalArray(state.history, 'state.history', 'E_INPUT_SHAPE')
+  const constraints = optionalArray(state.constraints, 'state.constraints', 'E_INPUT_SHAPE')
+  const lineage = state.lineage === undefined || state.lineage === null ? {} : assertPlainObject(state.lineage, 'state.lineage', 'E_INPUT_SHAPE')
+  const means = arg.means === undefined || arg.means === null ? null : assertArray(arg.means, 'means', 'E_INPUT_SHAPE')
+  const options = arg.options === undefined || arg.options === null ? {} : assertPlainObject(arg.options, 'options', 'E_INPUT_SHAPE')
+
+  const lineageKeys = Object.keys(lineage)
+  const roundIds = history.map((h) => h?.roundId).filter(nonEmptyString)
+
+  /** 证据引用解析器：引用必须能在**本次输入内**落到一个真实对象上，否则不算证据。 */
+  const resolveRef = (ref) => {
+    if (!nonEmptyString(ref)) return null
+    if (Object.prototype.hasOwnProperty.call(metrics, ref)) return { kind: 'metric', id: ref }
+    if (lineageKeys.includes(ref)) return { kind: 'lineage', id: ref }
+    if (roundIds.includes(ref)) return { kind: 'round', id: ref }
+    const [prefix, ...rest] = ref.split(':')
+    const tail = rest.join(':')
+    if (prefix === 'metric' && Object.prototype.hasOwnProperty.call(metrics, tail)) return { kind: 'metric', id: tail }
+    if (prefix === 'lineage' && lineageKeys.includes(tail)) return { kind: 'lineage', id: tail }
+    if (prefix === 'round' && roundIds.includes(tail)) return { kind: 'round', id: tail }
+    return null
+  }
+
+  // ── ② 逐度量造候选 ──
+  const goals = []
+  const reasons = []
+
+  for (const metricId of Object.keys(metrics).sort()) {
+    const m = metrics[metricId]
+    const base = {
+      goalId: `goal:${metricId}`,
+      targetMetric: metricId,
+      evidenceRefs: [],
+      priority: null,
+      priorityBasis: 'unavailable',
+    }
+    if (!isPlain(metrics[metricId])) {
+      goals.push(blocked(base, 'E_GOAL_MEANINGLESS', `度量 ${metricId} 不是对象 ⇒ 无可测目标`, 'unmeasurable'))
+      continue
+    }
+    const refs = Array.isArray(m.evidenceRefs) ? m.evidenceRefs : []
+    const resolvable = refs.filter((r) => resolveRef(r) !== null)
+    const unresolvable = refs.filter((r) => resolveRef(r) === null)
+
+    if (!finiteNumber(m.value)) {
+      goals.push(blocked({ ...base, evidenceRefs: uniqSorted(resolvable) }, 'E_GOAL_MEANINGLESS', `度量 ${metricId} 的 value 不是有限数 ⇒ 不可测`, 'unmeasurable'))
+      continue
+    }
+    const direction = directionOf(m.direction)
+    if (direction === null) {
+      goals.push(blocked({ ...base, evidenceRefs: uniqSorted(resolvable) }, 'E_GOAL_MEANINGLESS', `度量 ${metricId} 未声明合法 direction ⇒ 无可测目标`, 'unmeasurable'))
+      continue
+    }
+    if (refs.length === 0) {
+      goals.push(blocked({ ...base }, 'E_GOAL_MEANINGLESS', `度量 ${metricId} 未附任何证据引用 ⇒ 无证据的目标不得被提出`, 'no-evidence'))
+      continue
+    }
+    if (unresolvable.length > 0) {
+      goals.push(blocked({ ...base, evidenceRefs: uniqSorted(resolvable) }, 'E_GOAL_MEANINGLESS', `度量 ${metricId} 的证据引用无法在本次输入内解析：${unresolvable.join(', ')} ⇒ 视为无证据`, 'unresolvable-evidence'))
+      continue
+    }
+
+    // 期望增量的来源（只有两种，都要可复核）
+    let expectedDelta = null
+    let deltaBasis = null
+    let deltaRefs = []
+    if (finiteNumber(m.expectedDelta)) {
+      expectedDelta = m.expectedDelta
+      deltaBasis = 'declared'
+      deltaRefs = uniqSorted(resolvable)
+    } else {
+      const rounds = history.filter((h) => h && h.targetMetric === metricId && h.outcome === 'success' && finiteNumber(h.delta))
+      if (rounds.length > 0) {
+        expectedDelta = median(rounds.map((h) => h.delta))
+        deltaBasis = `history-median(${rounds.length})`
+        deltaRefs = uniqSorted(rounds.map((h) => `round:${h.roundId}`))
+      }
+    }
+    const evidenceRefs = uniqSorted([...resolvable, ...deltaRefs])
+
+    if (expectedDelta === null) {
+      goals.push(blocked({ ...base, evidenceRefs }, 'E_GOAL_MEANINGLESS', `度量 ${metricId} 既无自带 expectedDelta，也无成功轮次的实测 delta ⇒ 期望增量无来源（不猜）`, 'no-delta-source'))
+      continue
+    }
+
+    // 可达性
+    if (m.atBound === true) {
+      goals.push(blocked({ ...base, evidenceRefs, expectedDelta }, 'E_GOAL_UNREACHABLE', `度量 ${metricId} 已声明 atBound=true ⇒ 无改进余量`, 'at-bound'))
+      continue
+    }
+    if (!(expectedDelta > 0)) {
+      goals.push(blocked({ ...base, evidenceRefs, expectedDelta }, 'E_GOAL_UNREACHABLE', `度量 ${metricId} 的期望增量 ${expectedDelta} ≤ 0 ⇒ 按当前证据并不比现状更好`, 'non-positive-delta'))
+      continue
+    }
+    if (means !== null) {
+      const covering = means.filter((x) => x && Array.isArray(x.targets) && x.targets.includes(metricId))
+      if (covering.length === 0) {
+        goals.push(blocked({ ...base, evidenceRefs, expectedDelta }, 'E_GOAL_UNREACHABLE', `已声明的 ${means.length} 个手段中没有任何一个覆盖度量 ${metricId} ⇒ 无可达路径`, 'no-means'))
+        continue
+      }
+    }
+
+    const priority = m.value !== 0 ? Math.abs(expectedDelta) / Math.abs(m.value) : null
+    goals.push({
+      ...base,
+      statement: `${direction === 'higher-is-better' ? '提升' : '降低'} ${metricId}（当前 ${m.value}${nonEmptyString(m.unit) ? ` ${m.unit}` : ''}），期望改进量 ${expectedDelta}（依据 ${deltaBasis}）`,
+      direction,
+      expectedDelta,
+      rationale: `期望增量来源=${deltaBasis}；证据引用=${evidenceRefs.join(', ') || '无'}`,
+      evidenceRefs,
+      priority,
+      priorityBasis: priority === null ? 'unavailable' : 'relative-to-current',
+    })
+  }
+
+  // ── ③ 冲突检测：只依据**已声明**的关系，双方都 blocked ──
+  applyConflicts(goals, constraints)
+
+  // ── ④ 排序（全序） ──
+  goals.sort(compareGoals)
+  const limited = Number.isInteger(options.maxGoals) && options.maxGoals >= 0 ? goals.slice(0, options.maxGoals) : goals
+
+  if (limited.length === 0) reasons.push('metrics 存在但没有任何度量能产出可复核的候选（详见各 blocked 原因）')
+
+  return {
+    capability: CAPABILITY_ID,
+    version: CAPABILITY_VERSION,
+    goals: limited,
+    refused: false,
+    code: null,
+    reasons,
+    evidenceRefs: uniqSorted([...lineageKeys.map((k) => `lineage:${k}`), ...roundIds.map((r) => `round:${r}`), ...Object.keys(metrics).map((k) => `metric:${k}`)]),
+  }
+}
+
+function isPlain(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v)
+}
+
+function blocked(base, code, reason, tag) {
+  return {
+    goalId: base.goalId,
+    statement: `（已阻断）${base.targetMetric}`,
+    targetMetric: base.targetMetric,
+    // 被阻断的候选**不伪造**方向与增量：null 表示"没有可复核的值"，而不是 0/'higher-is-better'。
+    // （把 0 写成"期望增量为零"、把占位方向写成"想要提升"，都是产物带假证据。）
+    direction: base.direction ?? null,
+    expectedDelta: finiteNumber(base.expectedDelta) ? base.expectedDelta : null,
+    rationale: `${tag}: ${reason}`,
+    evidenceRefs: base.evidenceRefs ?? [],
+    priority: null,
+    priorityBasis: 'unavailable',
+    blocked: { code, reason },
+  }
+}
+
+/** 已声明的关系里，冲突双方**都**被阻断并互相点名 —— 不静默选边。 */
+function applyConflicts(goals, constraints) {
+  const byMetric = new Map(goals.map((g) => [g.targetMetric, g]))
+  const pairs = []
+  for (const c of constraints) {
+    if (!c || typeof c !== 'object') continue
+    const between = Array.isArray(c.between) ? c.between.filter(nonEmptyString) : []
+    if (c.kind === 'tradeoff' || c.kind === 'mutually-exclusive') {
+      for (let i = 0; i < between.length; i += 1) {
+        for (let j = i + 1; j < between.length; j += 1) pairs.push([between[i], between[j], c.id ?? 'constraint'])
+      }
+    }
+  }
+  for (const [a, b, cid] of pairs) {
+    const ga = byMetric.get(a)
+    const gb = byMetric.get(b)
+    if (!ga || !gb) continue
+    // 已经因更具体的理由（无意义/不可达）被阻断的候选不再被覆盖：
+    // 冲突不是它的首要病因，替换掉会更难定位。
+    if (ga.blocked || gb.blocked) continue
+    // 冲突关系覆盖既有阻断（冲突本身也是阻断理由之一），但保留原 code 里的更具体信息
+    block(ga, 'E_GOAL_CONFLICT', `与目标 ${gb.goalId} 冲突（已声明关系 ${cid}：${a} ↔ ${b}）—— 冲突不由本能力替调用方裁决`, [gb.goalId])
+    block(gb, 'E_GOAL_CONFLICT', `与目标 ${ga.goalId} 冲突（已声明关系 ${cid}：${a} ↔ ${b}）—— 冲突不由本能力替调用方裁决`, [ga.goalId])
+  }
+}
+
+function block(goal, code, reason, conflictsWith) {
+  goal.blocked = { code, reason, conflictsWith }
+  goal.rationale = `${goal.rationale}｜冲突：${reason}`
+}
+
+/** 全序：未阻断在前 → priority 降序（null 在后）→ goalId 升序。 */
+function compareGoals(a, b) {
+  const ba = a.blocked ? 1 : 0
+  const bb = b.blocked ? 1 : 0
+  if (ba !== bb) return ba - bb
+  const pa = finiteNumber(a.priority) ? a.priority : null
+  const pb = finiteNumber(b.priority) ? b.priority : null
+  if (pa === null && pb !== null) return 1
+  if (pa !== null && pb === null) return -1
+  if (pa !== null && pb !== null && pa !== pb) return pb - pa
+  return a.goalId < b.goalId ? -1 : a.goalId > b.goalId ? 1 : 0
+}
+
+/** 供 index 侧做形状自检（本能力不自行抛 RsiLoopError 之外的错误）。 */
+export function assertGoalSettingOutput(out) {
+  if (!Array.isArray(out.goals)) throw new RsiLoopError('E_INPUT_SHAPE', 'goalSetting 输出缺 goals')
+  return out
+}

package/src/index.mjs

@@ -0,0 +1,135 @@
+/**
+ * @xiciyang/rsi-contract —— 五个「自」能力的**载体库** v0。
+ *
+ * ─────────────────────────── 这个库是什么 / 不是什么 ───────────────────────────
+ *
+ * **是**：五个能力各自的最小确定性实现 + 它们的 I/O schema + 声明的失败模式 + 机读清单。
+ *   goalSetting（目标设定）/ directionSelection（方向选择）/ effectJudgment（效果判定）/
+ *   riskAssessment（风险识别）/ rollbackDecision（回退决策）。
+ *
+ * **不是**：**不是循环**。本库**不含**任何编排、调度、迭代控制、重试、停止条件、
+ *   预算控制或状态持久化 —— 那些属于调用它的编排层。本库的每个能力都是**一次纯函数调用**：
+ *   给输入、出结论、附证据、自带阻断理由。逐轮推进是别人的事。
+ *   具体地：本库不 import `timer`、不读时钟、不写文件、不发请求、不开子进程。
+ *
+ * **也**：不 import 任何其它包（零运行时依赖）。需要文件系统/网络时，由调用方在**库外**取好数据，
+ *   以参数注入（沿用 `@xiciyang/state-core` 的方言约定：`parseFile(fs, path)` 而不是自己 import fs）。
+ *
+ * ─────────────────────────── 五条横切纪律 ───────────────────────────
+ *
+ * ① **每个产物自带证据**：`evidenceRefs` / `evidence` 使第三方能重算，
+ *    且产物**保证 JSON 可序列化**：不含函数、活对象、循环引用、非有限数。
+ *    （`directionSelection` 透传风险、`rollbackDecision` 透传产物清单时都做深拷贝 + 可 JSON 化校验。）
+ *
+ * ② **确定性**：同输入同输出。本库不读时钟、不用随机数、不依赖环境变量；
+ *    所有排序都是**全序**（带唯一 tiebreak），故输出与输入顺序无关。
+ *    产物里**没有任何时间字段**（时间戳可以存在，但只允许由调用方作为输入携带，
+ *    并且不得参与决策 —— `rollbackDecision` 明确不按 `verifiedAt` 排序）。
+ *
+ * ③ **fail-closed**：缺输入就拒绝，绝不猜。没有"兜底默认值"这条路径：
+ *    阈值/离散度/z 一律由调用方给出，缺即 `E_THRESHOLD_NOT_PROVIDED`；
+ *    无可信回退目标即 `E_NO_ROLLBACK_TARGET`；度量缺失即空目标列表 + `refused`。
+ *
+ * ④ **不自证**：能力不得消费自己的产物当验证。`effectJudgment` 的完整性证据必须由别处生产
+ *    （`integrity.producedBy === 'effectJudgment'` 直接判 `measurement-invalid`），
+ *    `verifyRollbackDecision` 的现场观测同理。
+ *
+ * ⑤ **声明即可枚举**：`CAPABILITY_MANIFEST` 给出每个能力的 id / version / input schema /
+ *    output schema / 失败模式（含"哪条测试会让它变红"）。CI 不需要跑实现就能枚举契约面。
+ *
+ * 契约细节与失败模式逐条说明见同目录 `CONTRACT.md`；工作区根有一份人读报告
+ * `RSI_SELF_CAPABILITIES.md`。
+ */
+
+import { CONTRACT_VERSION, CAPABILITY_VERSION } from './version.mjs'
+import {
+  ERROR_CODES, CAPABILITY_IDS, VOCAB, VERIFICATION_COMPARATORS,
+  buildManifest, assertManifestComplete, schemasFor, failureModesFor,
+} from './contract.mjs'
+import { RsiLoopError, canonicalJson, jsonSafeReport, jsonClone, DIRECTIONS } from './support.mjs'
+import { goalSetting } from './goal-setting.mjs'
+import { directionSelection, SELECTION_RULE, CONSTRAINT_SEMANTICS } from './direction-selection.mjs'
+import { effectJudgment, EFFECT_CHECK_ORDER } from './effect-judgment.mjs'
+import { riskAssessment, FACTOR_TABLE, QUALITY_FACTORS, RISK_ORDER, assertNoSafeLevel, factorTable } from './risk-assessment.mjs'
+import { rollbackDecision, verifyRollbackDecision, VERIFICATION_CRITERION } from './rollback-decision.mjs'
+import { significance, SIGNIFICANCE_CRITERION } from './criterion.mjs'
+
+export { CONTRACT_VERSION, CAPABILITY_VERSION }
+export { ERROR_CODES, CAPABILITY_IDS, VOCAB, VERIFICATION_COMPARATORS }
+export { RsiLoopError, DIRECTIONS }
+export { goalSetting, directionSelection, effectJudgment, riskAssessment, rollbackDecision, verifyRollbackDecision }
+export { significance, SIGNIFICANCE_CRITERION }
+export { SELECTION_RULE, CONSTRAINT_SEMANTICS, EFFECT_CHECK_ORDER, VERIFICATION_CRITERION, RISK_ORDER }
+/** 规范化（键序无关）JSON —— 确定性断言用；`JSON.stringify` 的键序取决于构造顺序，不可作指纹。 */
+export { canonicalJson, jsonClone }
+/** JSON 卫生自检：`{ ok, violations[] }`（不抛，因为它的用途正是把违规报出来）。 */
+export { jsonSafeReport }
+/** 风险因子词表只读副本（供 CI 枚举，不复制第二份实现）。 */
+export { factorTable, assertNoSafeLevel, FACTOR_TABLE, QUALITY_FACTORS }
+
+/** 五个能力的实现体（清单据此判定 `implemented`）。 */
+const IMPLEMENTATIONS = Object.freeze({
+  goalSetting,
+  directionSelection,
+  effectJudgment,
+  riskAssessment,
+  rollbackDecision,
+})
+
+/**
+ * **机读能力清单** —— 调用方与 CI 用它枚举能力、schema 与失败模式。
+ * 冻结（`Object.freeze`），防止运行期被改写后"契约"与"实现"分叉。
+ */
+export const CAPABILITY_MANIFEST = Object.freeze({
+  ...buildManifest(CAPABILITY_VERSION, IMPLEMENTATIONS),
+  contractVersion: CONTRACT_VERSION,
+  loopControlFlow: false,
+  runtimeDependencies: [],
+  jsonSafe: true,
+  deterministic: true,
+  timestampsAffectDecision: false,
+})
+
+/** 按 id 取一个能力的契约与实现（未知 id 抛错，不返回 undefined）。 */
+export function getCapability(id) {
+  const entry = CAPABILITY_MANIFEST.capabilities.find((c) => c.id === id)
+  if (!entry) throw new RsiLoopError('E_INPUT_SHAPE', `未知能力 id：${String(id)}（可用：${CAPABILITY_IDS.join(', ')}）`)
+  return { ...entry, schema: schemasFor(id), failureModes: failureModesFor(id), run: IMPLEMENTATIONS[id] }
+}
+
+/**
+ * 契约自检 —— 让"契约面完整"这件事**可执行**而不是靠人读文档：
+ *   ① 清单完整（五个能力 × id/两个 schema/实现/失败模式，且每条模式都指向会变红的测试）；
+ *   ② 风险词表里**不存在**"安全/无风险"档（有人加回来即红）；
+ *   ③ 若给了 `sourceText`，则必须同时给出**扫描词表** `patterns`，逐个检查是否出现 ——
+ *      词表**不由本库自带**：它是"什么算非确定性"的**判据**，判据属于调用方（这里是测试）。
+ *      给了源码却不给词表 ⇒ 报问题（fail-closed，绝不静默跳过扫描）。
+ *
+ * 为什么词表不写在本库源码里：写了就会让"源码不含非确定性调用"这条扫描**扫到自己**，
+ * 变成自指的假阳性。判据放在会调用它的测试里，扫描才是在扫实现。
+ *
+ * 返回 `{ ok, problems[] }`（不抛，因为它的用途正是把问题**报出来**）。
+ */
+export function verifyCapabilityContract({ sourceText = null, patterns = null } = {}) {
+  const problems = []
+  const m = assertManifestComplete(CAPABILITY_MANIFEST)
+  problems.push(...m.problems)
+  try {
+    assertNoSafeLevel()
+  } catch (e) {
+    problems.push(String(e.message))
+  }
+  if (typeof sourceText === 'string') {
+    if (!Array.isArray(patterns) || patterns.length === 0) {
+      problems.push('提供了 sourceText 但没有提供扫描词表 patterns ⇒ 扫描未执行（不得静默跳过）')
+    } else {
+      for (const bad of patterns) {
+        if (sourceText.includes(bad)) problems.push(`源码出现非确定性/环境相关调用：${bad}`)
+      }
+    }
+  }
+  return { ok: problems.length === 0, problems }
+}
+
+/** 默认自检（不含源码扫描；源码扫描由测试侧读文件并传入词表后执行）。 */
+export const CONTRACT_SELF_CHECK = verifyCapabilityContract()

package/src/risk-assessment.mjs

@@ -0,0 +1,186 @@
+/**
+ * risk-assessment.mjs —— 能力 ④「风险识别」。
+ *
+ * 输入：候选方向 + 系统状态。输出：`{ level, mitigations[], requiresHumanConfirmation, reasons[] }`。
+ *
+ * ─────────────────────────── 三条硬纪律 ───────────────────────────
+ *
+ * ① **未知不得等于安全**。词表外的因子、或**根本没有声明任何因子** ⇒ 直接升到 `critical`
+ *    且 `requiresHumanConfirmation: true`。词表里**没有 `none`/`safe` 这一档** ——
+ *    这不是"忘了写"，而是刻意的：风险档位的值域里不存在"安全"这个结论。
+ *
+ * ② **就地变更是独立风险档**（本仓库原则："就地变更失败是独立风险档"）。
+ *    只要 `irreversible === true` 或 `inPlace === true`，无论调用方列了什么因子，
+ *    都会**自动注入**因子 `irreversible-in-place`（档位 high），并在产物里标 `injected: true`。
+ *    即"调用方漏写 ⇒ 被结构事实补上"，而不是"漏写 ⇒ 被判为安全"。
+ *
+ * ③ **档位取上界（max），不取平均**。多个因子时取最高档 —— 平均值会把一个 critical
+ *    摊薄成 medium，那正是"低估风险"的机制化形态。
+ *
+ * ## 失败模式的检出方式（这是本能力最需要说清的一点）
+ *
+ * `低估风险` / `高估风险` **无法**从不含自评的输入里判定（没有"真值"可比）。
+ * 因此本能力要求调用方**可选地**给出 `declaredLevel`（它自己的判断），然后：
+ *   - `declaredLevel < 计算档位` ⇒ `E_RISK_UNDERESTIMATE`，**采用计算档位**（不采纳低估）；
+ *   - `declaredLevel > 计算档位` ⇒ `E_RISK_OVERESTIMATE`，报出来但**保留调用方的更高档位**
+ *     （把人的谨慎降下来是另一种错）；
+ *   - 未给自评 ⇒ `undeclared`，**既不因此升级也不因此降级**（不编造校准结论）。
+ * 另有一条**校准对照**（见 `tests/unit/risk-assessment.spec.mjs`）：一个已完全归类、
+ * 只读/可逆本地的方向必须落在 `low`。若实现恒判 `critical`，那条断言变红 —— 那是
+ * "高估风险"的可证伪面。
+ */
+
+import { CAPABILITY_VERSION } from './version.mjs'
+import { assertPlainObject, nonEmptyString, jsonClone, uniqSorted, optionalArray, RsiLoopError } from './support.mjs'
+import { VOCAB } from './contract.mjs'
+
+export const CAPABILITY_ID = 'riskAssessment'
+
+/** 档位的全序（取上界用）。 */
+export const RISK_ORDER = Object.freeze(['low', 'medium', 'high', 'critical'])
+
+/**
+ * 因子 → 档位 / 缓解措施的**冻结对照表**。
+ *
+ * 这张表是"已归类的风险事实"的全部词表。表外的一切都是**未识别**（⇒ critical）。
+ * 之所以是表而不是公式：风险档位是**判断**，把判断写成表使它可以被逐条审计与对照，
+ * 而"按某个公式算出来"会把判断藏在系数里（那正是"未识别"的伪装）。
+ */
+export const FACTOR_TABLE = Object.freeze({
+  'read-only-observation': { level: 'low', mitigation: '只读观测：不写入任何共享状态；保留原始观测记录' },
+  'reversible-local': { level: 'low', mitigation: '本地可逆：变更前快照，失败即恢复；不触碰共享状态根' },
+  'resource-consuming': { level: 'low', mitigation: '资源消耗：在预算上限内执行，超限暂停并报告（不降级）' },
+  'shared-state': { level: 'medium', mitigation: '共享状态：变更前备份并在链内记录；变更后复核内容哈希' },
+  'external-side-effect': { level: 'medium', mitigation: '外部副作用：先干跑（dry-run）确认影响面，再实施' },
+  'artifact-overwrite': { level: 'medium', mitigation: '覆盖产物：保留原件与内容哈希，覆盖前后逐位比对' },
+  'irreversible-in-place': { level: 'high', mitigation: '就地变更（独立风险档）：必须先产出完整回退目标（含产物哈希）并取得人工确认，方可执行' },
+  'irreproducible': { level: 'high', mitigation: '不可复现：把全部输入（种子/版本/数据哈希）随产物落盘，否则视为不可接受' },
+  'affects-eval-data': { level: 'high', mitigation: '触及评估数据：评估集是只读红线；任何写入必须先封印复核' },
+  'user-visible-position': { level: 'high', mitigation: '对外可见位点：须人工确认后执行，并保留可回退版本' },
+  /* ── 结果质量风险（R5-G2，2026-10-02 第五轮事故驱动）─────────────────────
+   * 由来：第五轮"延长训练"方向只声明了**过程**因子（resource-consuming / shared-state），
+   * 拿到 medium 档；而实际发生的代价是**模型被交易**——格式合规 0.126→0.602 的同时，
+   * wikitext NLL 统计显著退化（6.2× 于噪声界），是**工具侧的遗忘门**把它拦住的。
+   * ⇒ 系统会评"做这件事危不危险"，**不会**评"做完之后这还是不是原来那个东西"。
+   * 下面四个因子专门描述**结果质量**：执行成功 ≠ 资产没被弄坏。 */
+  'capability-tradeoff': { level: 'high', mitigation: '能力交易：明确声明"换取什么、付出什么"，并把**代价维度写进冻结判据**（G8 并列必过），不接受"只看目标指标"的验收' },
+  'distribution-shift': { level: 'high', mitigation: '分布偏移：目标分布外的度量（如通用语言建模）必须**前后各测一次**并给出噪声界' },
+  'task-overfit': { level: 'medium', mitigation: '任务过拟合：训练步数/轮次增加时须同时报告留出集与**非目标任务**的指标' },
+  'data-contamination': { level: 'high', mitigation: '数据污染：确认训练集与评估集内容哈希不相交（本仓库已有 seal 机制）' },
+})
+
+/** **结果质量**类因子（R5-G2）：只声明过程因子拿到的档位**不能代表**这类风险。 */
+export const QUALITY_FACTORS = Object.freeze(['capability-tradeoff', 'distribution-shift', 'task-overfit', 'data-contamination'])
+
+/** 自动注入的结构布尔 —— 它们不做判断，只是把"方向自己声明的结构事实"翻译成因子。 */
+const INJECTED_FACTORS = Object.freeze({
+  irreversible: 'irreversible-in-place',
+  inPlace: 'irreversible-in-place',
+})
+
+export function riskAssessment(input) {
+  const arg = assertPlainObject(input ?? {}, 'riskAssessment 入参', 'E_INPUT_SHAPE')
+  const direction = assertPlainObject(arg.direction ?? null, 'direction', 'E_INPUT_SHAPE')
+  if (!nonEmptyString(direction.id)) throw new RsiLoopError('E_INPUT_SHAPE', 'direction.id 必须是非空字符串')
+
+  const declared = optionalArray(direction.factors, 'direction.factors', 'E_INPUT_SHAPE').map(String)
+  const injected = Object.keys(INJECTED_FACTORS).filter((k) => direction[k] === true).map((k) => INJECTED_FACTORS[k])
+
+  // 未声明任何因子（含注入）⇒ 未识别。**注意这是"没有信息"，不是"没有风险"。**
+  const declaredNothing = declared.length === 0 && injected.length === 0
+  const factorNames = [...new Set([...declared, ...injected])].sort()
+
+  const reasons = []
+  const factorLevels = []
+  let level = null
+
+  if (declaredNothing) {
+    level = 'critical'
+    reasons.push('未声明任何风险因子 ⇒ 风险未识别（E_RISK_UNCLASSIFIED）⇒ 升到 critical（绝不判安全）')
+  } else {
+    for (const f of factorNames) {
+      const known = Object.prototype.hasOwnProperty.call(FACTOR_TABLE, f)
+      const lv = known ? FACTOR_TABLE[f].level : 'critical'
+      factorLevels.push({ factor: f, level: lv, known, injected: injected.includes(f) && !declared.includes(f) })
+      if (!known) reasons.push(`因子「${f}」不在已归类词表中 ⇒ 未识别 ⇒ 升到 critical（E_RISK_UNCLASSIFIED，fail-closed）`)
+    }
+    // 取上界
+    level = factorLevels.map((x) => x.level).reduce((a, b) => (RISK_ORDER.indexOf(b) > RISK_ORDER.indexOf(a) ? b : a), 'low')
+  }
+
+  // ── R5-G2：结果质量风险是否被声明（**可见性**，不改档位）──
+  const qualityDeclared = factorNames.filter((f) => QUALITY_FACTORS.includes(f))
+  if (!declaredNothing && qualityDeclared.length === 0) {
+    reasons.push('**未声明任何结果质量风险因子**（capability-tradeoff / distribution-shift / task-overfit / data-contamination 一个都没有）⇒ 本次评估只覆盖了"执行过程"风险，**没有覆盖"执行后资产是否被弄坏"**（第五轮实测：正是这一类被漏掉）')
+  }
+
+  const mitigations = uniqSorted(
+    factorNames
+      .map((f) => (Object.prototype.hasOwnProperty.call(FACTOR_TABLE, f) ? FACTOR_TABLE[f].mitigation : null))
+      .filter(Boolean)
+      .concat(declaredNothing ? ['未归类风险禁止在无人工确认的情况下执行'] : []),
+  )
+
+  // ── 自评校准（可选输入；不给就不编造校准结论） ──
+  const computedLevel = level
+  const hasUnknownFactor = factorLevels.some((f) => !f.known)
+  let verdict = 'undeclared'
+  // "未识别"是独立于自评的一等结论：没有因子、或有词表外的因子，都必须报出来。
+  let code = declaredNothing || hasUnknownFactor ? 'E_RISK_UNCLASSIFIED' : null
+  let declaredLevel = null
+  if (nonEmptyString(direction.declaredLevel)) {
+    if (!VOCAB.riskLevel.includes(direction.declaredLevel)) {
+      throw new RsiLoopError('E_INPUT_SHAPE', `direction.declaredLevel=${direction.declaredLevel} 不在 ${VOCAB.riskLevel.join('/')} 之内`)
+    }
+    declaredLevel = direction.declaredLevel
+    const d = RISK_ORDER.indexOf(declaredLevel)
+    const c = RISK_ORDER.indexOf(computedLevel)
+    if (d < c) {
+      verdict = 'underestimated'
+      code = 'E_RISK_UNDERESTIMATE'
+      reasons.push(`低估风险：自评 ${declaredLevel} 低于计算档位 ${computedLevel} ⇒ 采用计算档位（不采纳低估）`)
+    } else if (d > c) {
+      verdict = 'overestimated'
+      code = code ?? 'E_RISK_OVERESTIMATE'
+      level = declaredLevel // 保留更高档位：把人的谨慎降下来是另一种错
+      reasons.push(`高估风险：自评 ${declaredLevel} 高于计算档位 ${computedLevel} ⇒ 保留自评档位（本能力不替调用方降档）`)
+    } else {
+      verdict = 'consistent'
+    }
+  }
+
+  const requiresHumanConfirmation = level === 'high' || level === 'critical'
+  if (requiresHumanConfirmation) reasons.push(`档位 ${level} ⇒ requiresHumanConfirmation=true`)
+  if (injected.length > 0 && !declaredNothing) {
+    reasons.push(`由结构布尔自动注入因子：${uniqSorted(injected).join(', ')}（调用方未列出，但结构事实已声明）`)
+  }
+
+  return {
+    capability: CAPABILITY_ID,
+    version: CAPABILITY_VERSION,
+    level,
+    mitigations,
+    requiresHumanConfirmation,
+    reasons,
+    factorLevels,
+    calibration: { declaredLevel, computedLevel, verdict },
+    qualityRisk: { declared: qualityDeclared, vocabulary: [...QUALITY_FACTORS], covered: qualityDeclared.length > 0 },
+    refused: false,
+    code,
+    evidenceRefs: uniqSorted(Array.isArray(direction.evidenceRefs) ? direction.evidenceRefs.filter(nonEmptyString) : []),
+  }
+}
+
+/** 供 index 侧断言"词表里没有 safe/none 档"（这条断言会随任何人加回 safe 而变红）。 */
+export function assertNoSafeLevel() {
+  const bad = VOCAB.riskLevel.filter((l) => ['none', 'safe', 'no-risk'].includes(l))
+  if (bad.length > 0) throw new RsiLoopError('E_INPUT_SHAPE', `风险词表不得含"安全"档：${bad.join(', ')}`)
+  const badFactor = Object.entries(FACTOR_TABLE).filter(([, v]) => ['none', 'safe'].includes(v.level)).map(([k]) => k)
+  if (badFactor.length > 0) throw new RsiLoopError('E_INPUT_SHAPE', `因子 ${badFactor.join(', ')} 被归为"安全"档 —— 风险档位里不存在安全`)
+  return true
+}
+
+/** 只读暴露因子表（供测试与 CI 枚举，不复制第二份）。 */
+export function factorTable() {
+  return jsonClone(FACTOR_TABLE, 'FACTOR_TABLE')
+}