@xiciyang/rsi-contract 0.0.0-stage → 0.1.0

package/src/criterion.mjs

@@ -0,0 +1,48 @@
+/**
+ * criterion.mjs —— 显著性判据的**唯一一份实现**（本库内）。
+ *
+ * ## 为什么单独一个文件
+ *
+ * `effectJudgment` 要回答"这点改进是不是噪声"。判据形式在本仓库**已经冻结过**，
+ * 见 `inference-training/checks/overfit-criterion.mjs` 的 O2 判据：
+ *
+ *     improvement > z · SE          （单侧：留出集上的改进必须显著为正）
+ *
+ * 与 `@xiciyang/testing-core` 的 `dualGate` 同一条纪律：**先判测量是否成立，再判数值**。
+ * 本库**不新增第二套判据**，只把同一条形式落成一份实现，供 `effectJudgment` 调用。
+ *
+ * ## 与冻结实现的关系（可验证，不是口头声明）
+ *
+ * `tests/unit/effect-judgment.spec.mjs` 里有一条**跨实现一致性**断言：
+ * 若 `inference-training/checks/overfit-criterion.mjs` 可 import，
+ * 则本函数的 `significant` 位必须与 `evaluateOverfit(...).o2.pass` **逐例一致**。
+ * 该文件不在本库目录内（**只读引用，未修改**）；不可 import 时按仓库的 skip 通道显式登记，
+ * 不计入断言数（把"没跑"写成恒真断言会灌水指标）。
+ *
+ * ## 常量从哪来
+ *
+ * `z` 与 `SE` **一律由调用方给出**，本库**不含任何默认值** ——
+ * 硬编码 `z=1.96` 会让"判据是谁定的"这件事无解，而本仓库的红线是：
+ * **阈值必须由调用方显式给出，缺失即拒绝（fail-closed）**。
+ */
+
+/** 判据的可复核文本（随证据一起返回，使第三方不必读代码就知道用了什么公式）。 */
+export const SIGNIFICANCE_CRITERION = 'improvement > z · SE （单侧；z 与 SE 均由调用方给出，本库无默认值）'
+
+/**
+ * 单侧显著性判定。
+ * @param {{improvement:number, se:number, z:number}} p
+ * @returns {{significant:boolean, improvement:number, se:number, z:number, bound:number, criterion:string}}
+ */
+export function significance({ improvement, se, z } = {}) {
+  const d = Number(improvement)
+  const s = Number(se)
+  const zz = Number(z)
+  // 这里**不抛错也不兜底**：调用方的体检（三个值是否齐备/是否有限）在 effectJudgment 里
+  // 按"缺阈值 ⇒ refused"的语义处理；本函数只负责算，且拒绝把非有限值算成结论。
+  if (!Number.isFinite(d) || !Number.isFinite(s) || !Number.isFinite(zz)) {
+    return { significant: null, improvement: Number.isFinite(d) ? d : null, se: Number.isFinite(s) ? s : null, z: Number.isFinite(zz) ? zz : null, bound: null, criterion: SIGNIFICANCE_CRITERION }
+  }
+  const bound = zz * s
+  return { significant: d > bound, improvement: d, se: s, z: zz, bound, criterion: SIGNIFICANCE_CRITERION }
+}

package/src/direction-selection.mjs

@@ -0,0 +1,234 @@
+/**
+ * direction-selection.mjs —— 能力 ②「方向选择」。
+ *
+ * 输入：候选目标 + **声明的可用手段菜单**（+ 可选约束）。
+ * 输出：一个推荐方向 + 理由 + 期望收益 + **透传的风险** + 被考虑过的备选。
+ *
+ * ─────────────────────────── 四条硬纪律 ───────────────────────────
+ *
+ * ① **菜单之外的手段不可选**。`preferredMeansId` 不在 `means` 里 ⇒ 整体 refused。
+ *    "不可行"最纯粹的形态就是"它根本不在你能做的事的清单上"。
+ *
+ * ② **方向必须真的打在目标度量上**。手段的 `targets` 不含 `goal.targetMetric` ⇒ 不可采纳；
+ *    被 `preferredMeansId` 强制指定时整体拒绝（不偷偷换成别的目标）。
+ *
+ * ③ **风险必须透传，不得自产**。手段必须自带 `risk`（`riskAssessment` 的产物）。
+ *    缺 risk ⇒ 整体拒绝：选一个未评估风险的方向正是"风险未识别"的入口。
+ *    本能力**不做风险判断**，只把它原样搬进产物（深拷贝，产物自持）。
+ *
+ * ④ **记录被考虑过的备选**。每一个菜单项都要在 `alternativesConsidered` 里出现，
+ *    并带上"可采纳/被拒 + 稳定 code + 原因"。只报结论不报备选，等于让第三方无法复核选择。
+ *
+ * 选择规则写进产物（`selectionRule`）：在可采纳集合里取 `expectedGain` 最大者，
+ * 同值按 `meansId` 升序 —— **全序，与输入顺序无关**（确定性要求）。
+ */
+
+import { CAPABILITY_VERSION } from './version.mjs'
+import { assertPlainObject, assertArray, optionalArray, finiteNumber, directionOf, jsonClone, uniqSorted, nonEmptyString, RsiLoopError } from './support.mjs'
+import { VOCAB } from './contract.mjs'
+
+export const CAPABILITY_ID = 'directionSelection'
+
+/**
+ * **约束语义版本** —— 随产物返回，让第三方能回答"这个结论是用哪一版约束语义判的"。
+ *
+ * - `strict`（**默认，v2.0.0**）：`forbid-irreversible` 把 `irreversible === true` **或**
+ *   `inPlace === true` **都**算不可逆 —— 与 `riskAssessment` 的"`inPlace` ⇒ 自动注入
+ *   `irreversible-in-place`"**对齐**。
+ * - `legacy`（**v1.x 原样保留**）：只看 `means.irreversible`。经
+ *   `options.legacyForbidIrreversible = true` 启用，**仅用于对照与回退**。
+ *
+ * ## 为什么这是一次 major 变更（`CONTRACT.md` §5）
+ * v1.x 下，"声明了 `forbid-irreversible` 却选中就地变更手段"是**可能的**（已实测复现）。
+ * 两个能力对"什么算不可逆"的理解不一致，属于**判据形式**的变更 ⇒ 升 `CAPABILITY_VERSION`。
+ * 旧语义**不删除**：保留可回退路径，且新 spec 用**同一份输入**跑出两种结论作对照。
+ */
+export const CONSTRAINT_SEMANTICS = Object.freeze({
+  STRICT: 'strict-includes-inPlace@2',
+  LEGACY: 'legacy-means.irreversible-only@1',
+})
+
+export const SELECTION_RULE = '在"菜单内 ∧ 打在目标度量上 ∧ 满足全部声明约束 ∧ 已附带风险结论 ∧ 增益可测"的手段中，取 expectedGain 最大者；同值按 meansId 升序（全序，与输入顺序无关）。本能力不做风险判断，风险由 riskAssessment 产出后透传。`forbid-irreversible` 默认按 strict 语义判（irreversible 或 inPlace 皆算不可逆）；legacy 语义（只看 irreversible）经 options.legacyForbidIrreversible 启用。'
+
+export function directionSelection(input) {
+  const arg = assertPlainObject(input ?? {}, 'directionSelection 入参', 'E_INPUT_SHAPE')
+  const goal = assertPlainObject(arg.goal ?? null, 'goal', 'E_INPUT_SHAPE')
+  const means = assertArray(arg.means ?? null, 'means', 'E_INPUT_SHAPE')
+  const constraints = optionalArray(arg.constraints, 'constraints', 'E_INPUT_SHAPE')
+  const options = arg.options === undefined || arg.options === null ? {} : assertPlainObject(arg.options, 'options', 'E_INPUT_SHAPE')
+  // 缺省 = strict（fail-closed：不显式要求 legacy 就拿不到旧语义）
+  const legacyForbidIrreversible = options.legacyForbidIrreversible === true
+  const constraintSemantics = legacyForbidIrreversible ? CONSTRAINT_SEMANTICS.LEGACY : CONSTRAINT_SEMANTICS.STRICT
+
+  const goalMetric = nonEmptyString(goal.targetMetric) ? goal.targetMetric : null
+  const goalDirection = directionOf(goal.direction)
+  if (goalMetric === null || goalDirection === null) {
+    throw new RsiLoopError('E_INPUT_SHAPE', 'goal 必须给出非空 targetMetric 与合法 direction')
+  }
+  const goalRefs = Array.isArray(goal.evidenceRefs) ? goal.evidenceRefs.filter(nonEmptyString) : []
+
+  const base = {
+    capability: CAPABILITY_ID,
+    version: CAPABILITY_VERSION,
+    chosen: null,
+    rationale: '',
+    expectedGain: null,
+    risk: null,
+    alternativesConsidered: [],
+    refused: false,
+    code: null,
+    reasons: [],
+    evidenceRefs: uniqSorted(goalRefs),
+    selectionRule: SELECTION_RULE,
+    constraintSemantics,
+  }
+
+  // ── 菜单为空：refuse（不发散） ──
+  if (means.length === 0) {
+    return { ...base, refused: true, code: 'E_NO_MEANS', reasons: ['means 菜单为空 ⇒ 无任何可采纳方向（本库不发明手段）'] }
+  }
+
+  const menuIds = means.map((m) => m?.id).filter(nonEmptyString)
+  const byId = new Map()
+  for (const m of means) if (m && nonEmptyString(m.id)) byId.set(m.id, m)
+
+  // ── 逐手段判定可采纳性（顺序无关：全部算完再排序） ──
+  const considered = []
+  for (const m of means) {
+    considered.push(judgeMeans(m, { goalMetric, constraints, legacyForbidIrreversible }))
+  }
+  considered.sort((a, b) => (a.meansId < b.meansId ? -1 : a.meansId > b.meansId ? 1 : 0))
+  base.alternativesConsidered = considered.map(({ meansId, admissible, code, reason, expectedGain: eg, expectedGainBasis: eb }) => ({ meansId, admissible, code, reason, expectedGain: eg ?? null, expectedGainBasis: eb ?? null }))
+
+  // ── 调用方指定了手段：必须在菜单内，且必须真的可采纳 ──
+  if (arg.preferredMeansId !== undefined && arg.preferredMeansId !== null) {
+    const pid = String(arg.preferredMeansId)
+    if (!menuIds.includes(pid)) {
+      return {
+        ...base,
+        refused: true,
+        code: 'E_MEANS_NOT_IN_MENU',
+        reasons: [`preferredMeansId=${pid} 不在声明的菜单内（菜单：${menuIds.join(', ') || '空'}）⇒ 不可行，拒绝执行（fail-closed）`],
+      }
+    }
+    const c = considered.find((x) => x.meansId === pid)
+    if (!c.admissible) {
+      return {
+        ...base,
+        refused: true,
+        code: c.code,
+        reasons: [`preferredMeansId=${pid} 在菜单内但不可采纳：${c.reason}`],
+      }
+    }
+    return finalize(base, byId.get(pid), goalMetric, goalDirection, considered, goalRefs, '调用方指定且可采纳')
+  }
+
+  // ── 自动选择：可采纳集合里取 expectedGain 最大 ──
+  const admissible = considered.filter((c) => c.admissible)
+  if (admissible.length === 0) {
+    return {
+      ...base,
+      refused: true,
+      code: 'E_NO_ADMISSIBLE_MEANS',
+      reasons: [
+        `菜单内 ${considered.length} 个手段全部不可采纳 ⇒ 不选方向（拒绝理由见 alternativesConsidered）`,
+        ...considered.map((c) => `${c.meansId}: ${c.code} —— ${c.reason}`),
+      ],
+    }
+  }
+  // **R5-G3 排序修正**：先按依据（measured 优先），再按增益降序，最后按 meansId。
+  // 为什么依据优先于数值：第五轮实测"judged 0.05 / 实测 0.4761"——
+  // 拍出来的幅度**连量级都不可信**，让它和 measured 同权比较就是把噪声当信号。
+  admissible.sort((a, b) => {
+    const ba = a.expectedGainBasis === 'measured' ? 0 : 1
+    const bb = b.expectedGainBasis === 'measured' ? 0 : 1
+    if (ba !== bb) return ba - bb
+    if (a.expectedGain !== b.expectedGain) return b.expectedGain - a.expectedGain
+    return a.meansId < b.meansId ? -1 : a.meansId > b.meansId ? 1 : 0
+  })
+  const best = admissible[0]
+  return finalize(base, byId.get(best.meansId), goalMetric, goalDirection, considered, goalRefs, `可采纳集合中增益最大（${admissible.length} 个可采纳 / 共 ${considered.length} 个）`)
+}
+
+/** 单个手段的可采纳性判定 —— 四条闸门，返回稳定 code 与可直接展示的原因。 */
+function judgeMeans(m, { goalMetric, constraints, legacyForbidIrreversible = false }) {
+  if (!m || typeof m !== 'object') return { meansId: '(非对象)', admissible: false, code: 'E_INPUT_SHAPE', reason: '手段不是对象', expectedGain: null }
+  const meansId = nonEmptyString(m.id) ? m.id : '(无 id)'
+  const targets = Array.isArray(m.targets) ? m.targets : null
+  if (targets === null) return { meansId, admissible: false, code: 'E_INPUT_SHAPE', reason: '手段缺 targets 数组', expectedGain: null }
+
+  // ② 方向必须真的打在目标度量上
+  if (!targets.includes(goalMetric)) {
+    return { meansId, admissible: false, code: 'E_DIRECTION_MISMATCH', reason: `手段 targets=[${targets.join(', ')}] 不含目标度量 ${goalMetric} ⇒ 方向错误（改了别的东西）`, expectedGain: null }
+  }
+  // 增益必须可测
+  if (!finiteNumber(m.expectedGain)) {
+    return { meansId, admissible: false, code: 'E_MEANS_UNMEASURABLE', reason: 'expectedGain 不是有限数 ⇒ 无法比较收益（不猜）', expectedGain: null }
+  }
+  // **R5-G3**：增益必须声明**依据**（measured / judged）。
+  // 由来：第五轮实测 expectedGain 判断值 0.05，实得 0.4761（**差 9.5 倍**）——
+  // 幅度预测不可信。不区分依据，排序就等于拿"拍脑袋的数"和"量出来的数"同权比较。
+  const basis = m.expectedGainBasis
+  if (basis !== 'measured' && basis !== 'judged') {
+    return { meansId, admissible: false, code: 'E_GAIN_BASIS_MISSING', reason: `expectedGainBasis=${JSON.stringify(basis)} 不在 ['measured','judged'] 之内 ⇒ 无法判断这个增益是量出来的还是拍出来的（第五轮实测拍出来的偏了 9.5 倍）`, expectedGain: m.expectedGain }
+  }
+  // 声明为 measured ⇒ 必须给出可解析的来源引用（否则"measured"三个字就是空口）
+  if (basis === 'measured') {
+    const refs = Array.isArray(m.gainEvidenceRefs) ? m.gainEvidenceRefs.filter(nonEmptyString) : []
+    if (refs.length === 0) {
+      return { meansId, admissible: false, code: 'E_GAIN_BASIS_MISSING', reason: "expectedGainBasis='measured' 但没给 gainEvidenceRefs ⇒ '量出来的'必须能指到测量", expectedGain: m.expectedGain }
+    }
+  }
+  // ③ 风险必须透传
+  if (m.risk === undefined || m.risk === null || typeof m.risk !== 'object' || Array.isArray(m.risk)) {
+    return { meansId, admissible: false, code: 'E_RISK_MISSING', reason: '手段未附带 risk（riskAssessment 的产物）⇒ 不得选择未评估风险的方向', expectedGain: m.expectedGain }
+  }
+  if (!VOCAB.riskLevel.includes(m.risk.level)) {
+    return { meansId, admissible: false, code: 'E_RISK_MISSING', reason: `risk.level=${String(m.risk.level)} 不在词表内 ⇒ 风险结论不可用`, expectedGain: m.expectedGain }
+  }
+  // ④ 声明约束
+  for (const c of constraints) {
+    if (!c || typeof c !== 'object') continue
+    if (c.kind === 'forbid-means' && c.meansId === meansId) {
+      return { meansId, admissible: false, code: 'E_CONSTRAINT_VIOLATION', reason: `约束 ${c.id ?? '(无 id)'} 明令禁止手段 ${meansId}`, expectedGain: m.expectedGain }
+    }
+    if (c.kind === 'forbid-irreversible') {
+      // **strict（默认）**：`inPlace` 同样算不可逆 —— 与 riskAssessment 的自动注入判据对齐。
+      // **legacy**：只看 `irreversible`（v1.x 原样行为，仅供对照/回退）。
+      // 判据基于**结构布尔**，不看调用方有没有把因子列进 `factors` ——
+      // 漏写因子正是"风险未识别"的入口（`riskAssessment` 在那边用注入兜住，这里用结构布尔兜住）。
+      const irreversible = m.irreversible === true
+      const inPlace = m.inPlace === true
+      const blocked = legacyForbidIrreversible ? irreversible : (irreversible || inPlace)
+      if (blocked) {
+        return {
+          meansId, admissible: false, code: 'E_CONSTRAINT_VIOLATION',
+          reason: `约束 ${c.id ?? '(无 id)'} 禁止不可逆手段，而本手段 declared irreversible=${irreversible} / inPlace=${inPlace}`
+            + (legacyForbidIrreversible
+              ? '（legacy 语义：只看 irreversible —— 这正是要保留的对照）'
+              : '（strict 语义：inPlace 同样算不可逆，与 riskAssessment 的自动注入一致）'),
+          expectedGain: m.expectedGain,
+        }
+      }
+    }
+    if (c.kind === 'require-target' && Array.isArray(c.targets) && !c.targets.every((t) => targets.includes(t))) {
+      return { meansId, admissible: false, code: 'E_CONSTRAINT_VIOLATION', reason: `约束 ${c.id ?? '(无 id)'} 要求覆盖 [${c.targets.join(', ')}]，本手段只覆盖 [${targets.join(', ')}]`, expectedGain: m.expectedGain }
+    }
+  }
+  return { meansId, admissible: true, code: null, reason: null, expectedGain: m.expectedGain, expectedGainBasis: basis }
+}
+
+function finalize(base, means, goalMetric, goalDirection, considered, goalRefs, why) {
+  const m = means
+  const meansRefs = Array.isArray(m.evidenceRefs) ? m.evidenceRefs.filter(nonEmptyString) : []
+  // 风险**透传**：深拷贝（jsonClone 同时证明它可 JSON 化），并原样记录来源手段。
+  const risk = jsonClone(m.risk, `means[${m.id}].risk`)
+  return {
+    ...base,
+    chosen: { meansId: m.id, targetMetric: goalMetric, direction: goalDirection, expectedGain: m.expectedGain },
+    rationale: `${why}。选中 ${m.id}：expectedGain=${m.expectedGain}；风险档位 ${risk.level}（**透传自 riskAssessment，本能力未自行评估**）。被考虑过的备选：${considered.filter((c) => c.meansId !== m.id).map((c) => `${c.meansId}(${c.admissible ? '可采纳但增益较低' : c.code})`).join(', ') || '无'}`,
+    expectedGain: m.expectedGain,
+    risk,
+    evidenceRefs: uniqSorted([...goalRefs, ...meansRefs]),
+  }
+}

package/src/effect-judgment.mjs

@@ -0,0 +1,210 @@
+/**
+ * effect-judgment.mjs —— 能力 ③「效果判定」（五个能力里最重要的一个）。
+ *
+ * 输入：before/after 指标 **+ 测量完整性**（attempted/succeeded/failed/partial + 评估集身份）+ 阈值 + 离散度。
+ * 输出：`{ verdict: 'success' | 'failure' | 'measurement-invalid', evidence, reasons[] }`。
+ *
+ * ─────────────────────────── 它必须做的事（按契约） ───────────────────────────
+ *
+ * ① **不自证**。完整性证据必须由**别处**生产；`integrity.producedBy === 'effectJudgment'` 直接判无效。
+ *    自产的"我测过了"不是证据。
+ *
+ * ② **测量不成立 ⇒ 永不 success**。完整性缺失 / `failed > 0` / `partial === true` / 零样本
+ *    ⇒ `measurement-invalid`。这条与缺陷 14 同源：**不完整的测量不是测量**。
+ *
+ * ③ **跨评估集不比 Δ**。两侧 `datasetHash` 不同或缺哈希 ⇒ `measurement-invalid`。
+ *    依据 `inference-contracts/contracts/eval-contract.md` §7：Δ 只在同一 `datasetHash` 内可比。
+ *
+ * ④ **噪声内不得判成功**。`improvement ≤ z·SE` ⇒ `failure` + `inconclusive: true`。
+ *    判据形式与 `inference-training/checks/overfit-criterion.mjs` 的 O2 判据逐字一致
+ *    （见 `criterion.mjs`），且 `z`/`SE` **由调用方给出** —— 本库没有 1.96 这样的默认值。
+ *    缺阈值 ⇒ `E_THRESHOLD_NOT_PROVIDED`（refused），**绝不自行发明判据**。
+ *
+ * ## 判定顺序与可区分性
+ *
+ * 全部有效性检查**都跑完**再下结论（`reasons[]` 列出全部失败项），
+ * 但 `code` 取**固定优先级**里的第一条 —— 于是"同一个坏测量"的产物是确定的（确定性要求），
+ * 且不同病因的 `code` 互不相同（可区分性要求）。顺序见 `EFFECT_CHECK_ORDER`。
+ */
+
+import { CAPABILITY_VERSION } from './version.mjs'
+import { assertPlainObject, finiteNumber, nonEmptyString, directionOf, jsonClone, uniqSorted, improvementOf, RsiLoopError } from './support.mjs'
+import { significance, SIGNIFICANCE_CRITERION } from './criterion.mjs'
+
+export const CAPABILITY_ID = 'effectJudgment'
+
+/** 有效性检查的固定顺序（`code` 取第一条失败项；测试据此断言覆盖率）。 */
+export const EFFECT_CHECK_ORDER = Object.freeze([
+  'E_INTEGRITY_MISSING',
+  'E_MEASUREMENT_INCOMPLETE',
+  'E_NO_SAMPLES',
+  'E_METRIC_MISMATCH',
+  'E_METRIC_VALUE_MISSING',
+  'E_DATASET_IDENTITY_MISSING',
+  'E_DATASET_MISMATCH',
+  'E_SELF_JUDGING',
+  'E_THRESHOLD_NOT_PROVIDED',
+])
+
+export function effectJudgment(input) {
+  const arg = assertPlainObject(input ?? {}, 'effectJudgment 入参', 'E_INPUT_SHAPE')
+  const before = assertPlainObject(arg.before ?? null, 'before', 'E_INPUT_SHAPE')
+  const after = assertPlainObject(arg.after ?? null, 'after', 'E_INPUT_SHAPE')
+  const direction = directionOf(arg.direction)
+  if (direction === null) throw new RsiLoopError('E_INPUT_SHAPE', 'direction 必须是 higher-is-better / lower-is-better 之一')
+
+  const integrity = arg.integrity
+  const threshold = arg.threshold
+  const noise = arg.noise
+
+  const failures = []
+  const add = (code, reason) => failures.push({ code, reason })
+
+  /* ① 完整性证据本身存不存在（`未知 ≠ 已知完整`） */
+  let hasIntegrity = false
+  if (integrity === undefined || integrity === null || typeof integrity !== 'object' || Array.isArray(integrity)) {
+    add('E_INTEGRITY_MISSING', 'integrity 缺失 ⇒ 不知道这次测量成不成立（缺证据不得当作完整）')
+  } else if (!finiteNumber(integrity.attempted) || !finiteNumber(integrity.succeeded) || !finiteNumber(integrity.failed) || typeof integrity.partial !== 'boolean') {
+    add('E_INTEGRITY_MISSING', 'integrity 缺 attempted/succeeded/failed/partial 中的字段，或类型不对 ⇒ 无法判定测量完整性')
+  } else if (integrity.succeeded > integrity.attempted) {
+    add('E_INTEGRITY_MISSING', `integrity 自相矛盾：succeeded(${integrity.succeeded}) > attempted(${integrity.attempted})`)
+  } else {
+    hasIntegrity = true
+  }
+
+  /* ② 不完整的测量不是测量（缺陷 14 的正面防线） */
+  if (hasIntegrity) {
+    if (integrity.failed > 0 || integrity.partial === true) {
+      add('E_MEASUREMENT_INCOMPLETE', `测量不完整：failed=${integrity.failed}/attempted=${integrity.attempted}、partial=${integrity.partial} ⇒ 不完整测量不得判 success`)
+    }
+    if (integrity.succeeded <= 0 || integrity.attempted <= 0) {
+      add('E_NO_SAMPLES', `零成功样本：succeeded=${integrity.succeeded}/attempted=${integrity.attempted} ⇒ 没有可判定的测量`)
+    }
+  }
+
+  /* ③ 前后必须是同一个度量 */
+  if (nonEmptyString(before.metric) && nonEmptyString(after.metric) && before.metric !== after.metric) {
+    add('E_METRIC_MISMATCH', `before.metric=${before.metric} ≠ after.metric=${after.metric} ⇒ 两个不同度量之间没有 Δ`)
+  }
+
+  /* ④ 测量值必须在场（缺值不得当 0） */
+  if (!finiteNumber(before.value) || !finiteNumber(after.value)) {
+    add('E_METRIC_VALUE_MISSING', `测量值缺失：before.value=${fmt(before.value)}、after.value=${fmt(after.value)} ⇒ 缺值不得当 0 参与判定`)
+  }
+
+  /* ⑤ 评估集身份（eval-contract §7） */
+  const hb = nonEmptyString(before.datasetHash) ? before.datasetHash : null
+  const ha = nonEmptyString(after.datasetHash) ? after.datasetHash : null
+  if (hb === null || ha === null) {
+    add('E_DATASET_IDENTITY_MISSING', `评估集身份缺失：before.datasetHash=${fmt(hb)}、after.datasetHash=${fmt(ha)} ⇒ 不可复核 ⇒ 不得判定`)
+  } else if (hb !== ha) {
+    add('E_DATASET_MISMATCH', `跨评估集比较：before.datasetHash=${hb} ≠ after.datasetHash=${ha} ⇒ Δ 只在同一 datasetHash 内可比（eval-contract §7.1）`)
+  }
+
+  /* ⑥ 自证防线 */
+  if (integrity && typeof integrity === 'object' && !Array.isArray(integrity) && integrity.producedBy === CAPABILITY_ID) {
+    add('E_SELF_JUDGING', `integrity.producedBy=${CAPABILITY_ID} ⇒ 本能力在用自己的产物当验证（自证不算证据）`)
+  }
+
+  /* ⑦ 阈值：缺失即拒绝，不发明判据 */
+  const minDelta = threshold && typeof threshold === 'object' && !Array.isArray(threshold) ? threshold.minDelta : undefined
+  const se = noise && typeof noise === 'object' && !Array.isArray(noise) ? noise.se : undefined
+  const z = noise && typeof noise === 'object' && !Array.isArray(noise) ? noise.z : undefined
+  const thresholdsOk =
+    finiteNumber(minDelta) && finiteNumber(se) && finiteNumber(z) && se >= 0 && z >= 0
+  if (!thresholdsOk) {
+    add('E_THRESHOLD_NOT_PROVIDED', `判据输入不完整或非法：minDelta=${fmt(minDelta)}、se=${fmt(se)}、z=${fmt(z)}（须为有限数且 se/z ≥ 0；本库不提供默认阈值/默认 z）`)
+  }
+
+  /* ── 结算 ── */
+  const refs = uniqSorted([
+    ...(Array.isArray(before.evidenceRefs) ? before.evidenceRefs.filter(nonEmptyString) : []),
+    ...(Array.isArray(after.evidenceRefs) ? after.evidenceRefs.filter(nonEmptyString) : []),
+    ...(integrity && Array.isArray(integrity.evidenceRefs) ? integrity.evidenceRefs.filter(nonEmptyString) : []),
+  ])
+
+  const commonEvidence = {
+    metric: nonEmptyString(before.metric) ? before.metric : nonEmptyString(after.metric) ? after.metric : null,
+    direction,
+    datasetHash: hb !== null && hb === ha ? hb : null,
+    integrity: integrity && typeof integrity === 'object' && !Array.isArray(integrity) ? jsonClone(integrity, 'integrity') : null,
+    values: {
+      before: finiteNumber(before.value) ? before.value : null,
+      after: finiteNumber(after.value) ? after.value : null,
+      improvement: null,
+      minDelta: finiteNumber(minDelta) ? minDelta : null,
+      se: finiteNumber(se) ? se : null,
+      z: finiteNumber(z) ? z : null,
+      noiseBound: null,
+      criterion: thresholdsOk ? SIGNIFICANCE_CRITERION : null,
+    },
+  }
+
+  if (failures.length > 0) {
+    const primary = EFFECT_CHECK_ORDER.map((c) => failures.find((f) => f.code === c)).find(Boolean) ?? failures[0]
+    return {
+      capability: CAPABILITY_ID,
+      version: CAPABILITY_VERSION,
+      verdict: 'measurement-invalid',
+      refused: true,
+      code: primary.code,
+      evidence: commonEvidence,
+      reasons: failures.map((f) => `${f.code}: ${f.reason}`),
+      evidenceRefs: refs,
+    }
+  }
+
+  /* 全部有效性通过 ⇒ 才谈数值 */
+  const improvement = improvementOf({ before: before.value, after: after.value, direction })
+  const sig = significance({ improvement, se, z })
+  const evidence = { ...commonEvidence, values: { ...commonEvidence.values, improvement, noiseBound: sig.bound, criterion: SIGNIFICANCE_CRITERION } }
+
+  if (!sig.significant) {
+    return {
+      capability: CAPABILITY_ID,
+      version: CAPABILITY_VERSION,
+      verdict: 'failure',
+      refused: false,
+      code: 'E_WITHIN_NOISE',
+      inconclusive: true,
+      evidence,
+      reasons: [
+        `改进量 ${fmt(improvement)} 未超过噪声界 z·SE = ${fmt(z)}×${fmt(se)} = ${fmt(sig.bound)} ⇒ 落在测量噪声内，**不得判 success**（判据：${SIGNIFICANCE_CRITERION}）`,
+      ],
+      evidenceRefs: refs,
+    }
+  }
+
+  if (improvement < minDelta) {
+    return {
+      capability: CAPABILITY_ID,
+      version: CAPABILITY_VERSION,
+      verdict: 'failure',
+      refused: false,
+      code: 'E_BELOW_THRESHOLD',
+      inconclusive: false,
+      evidence,
+      reasons: [`改进量 ${fmt(improvement)} 显著（> ${fmt(sig.bound)}）但未达阈值 minDelta=${fmt(minDelta)} ⇒ 未达标`],
+      evidenceRefs: refs,
+    }
+  }
+
+  return {
+    capability: CAPABILITY_ID,
+    version: CAPABILITY_VERSION,
+    verdict: 'success',
+    refused: false,
+    code: null,
+    inconclusive: false,
+    evidence,
+    reasons: [
+      `测量成立（failed=${integrity.failed}/attempted=${integrity.attempted}、partial=${integrity.partial}、datasetHash=${hb}）`,
+      `改进量 ${fmt(improvement)} > 噪声界 ${fmt(sig.bound)} 且 ≥ 阈值 ${fmt(minDelta)}`,
+    ],
+    evidenceRefs: refs,
+  }
+}
+
+function fmt(v) {
+  return typeof v === 'number' ? String(v) : String(v)
+}