@xiciyang/rsi-contract 0.0.0-stage → 0.1.0

package/src/rollback-decision.mjs

@@ -0,0 +1,248 @@
+/**
+ * rollback-decision.mjs —— 能力 ⑤「回退决策」。
+ *
+ * 输入：故障态 + 版本历史（已知良好状态及其产物标识）。
+ * 输出：`{ target, path, verification }` —— 回到哪个状态、怎么回、**怎么核验它真的生效了**。
+ *
+ * ─────────────────────────── 三条硬纪律 ───────────────────────────
+ *
+ * ① **没有可信目标就拒绝**。只有"`verifiedGood === true` **且**有 `verifiedBy` **且**产物带内容哈希"
+ *    的既往状态才算可信。一条都没有 ⇒ `refused: true` + `E_NO_ROLLBACK_TARGET`。**不猜最近的那个。**
+ *
+ * ② **核验必须落在产物上**（本仓库原文："只断言过程抓不到空操作，必须断言权重"）。
+ *    `verification.kind` 只允许 `artifact-content-hash`，`comparator` 只允许 `sha256-equal`。
+ *    调用方若自带"看退出码就算回退成功"的方案 ⇒ `E_PROCESS_ONLY_VERIFICATION` 拒绝。
+ *    每个 check 都带上 `notBeforeSha256`（故障态哈希）：**哈希没变就是空操作**，必须判失败。
+ *
+ * ③ **时间戳不参与决策**。排序只按 `seq`（缺失则按输入数组下标，并在 `orderingBasis` 里标明）。
+ *    这就是确定性要求的具体形态：同一组状态，不管 `verifiedAt` 怎么改，回退目标不变。
+ *
+ * ## 三个失败模式怎么被检出
+ *   - 回退失败：无可信目标（决策期）／observed 与目标哈希不符（核验期）；
+ *   - 回退到错误版本：observed 哈希能归属到**别的**历史状态 ⇒ 指名报出是哪一个；
+ *   - 回退不彻底：目标未覆盖故障态的全部产物（决策期即排除）／observed 缺某个必需产物的哈希（核验期）。
+ */
+
+import { CAPABILITY_VERSION } from './version.mjs'
+import { assertPlainObject, assertArray, optionalArray, isContentHash, nonEmptyString, uniqSorted, jsonClone, RsiLoopError } from './support.mjs'
+import { VERIFICATION_COMPARATORS } from './contract.mjs'
+
+export const CAPABILITY_ID = 'rollbackDecision'
+
+export const VERIFICATION_CRITERION = '回退后逐产物比对 sha256：必须等于目标状态登记的内容哈希（notBeforeSha256 相同的产物即空操作，判失败）。过程断言（退出码/日志/服务可用）只作补充，**不构成核验**。'
+
+export function rollbackDecision(input) {
+  const arg = assertPlainObject(input ?? {}, 'rollbackDecision 入参', 'E_INPUT_SHAPE')
+  const failure = assertPlainObject(arg.failure ?? null, 'failure', 'E_INPUT_SHAPE')
+  const history = assertArray(arg.history ?? null, 'history', 'E_INPUT_SHAPE')
+
+  const failureArtifacts = collectArtifacts(failure.artifacts, 'failure.artifacts')
+  const failureHashes = hashesOf(failureArtifacts)
+  const refs = uniqSorted([
+    ...(Array.isArray(failure.evidenceRefs) ? failure.evidenceRefs.filter(nonEmptyString) : []),
+    ...history.flatMap((h) => (h && Array.isArray(h.evidenceRefs) ? h.evidenceRefs.filter(nonEmptyString) : [])),
+  ])
+
+  const base = {
+    capability: CAPABILITY_ID,
+    version: CAPABILITY_VERSION,
+    target: null,
+    path: null,
+    verification: null,
+    refused: true,
+    code: null,
+    reasons: [],
+    evidence: { failureHashes, considered: [] },
+    evidenceRefs: refs,
+  }
+
+  // ── 故障态必须有哈希，否则连"空操作"都抓不到 ──
+  if (failureArtifacts.length === 0) {
+    return { ...base, code: 'E_ARTIFACT_SET_MISMATCH', reasons: ['failure.artifacts 为空或没有任何带合法 sha256 的产物 ⇒ 无法核验回退是否生效（fail-closed）'] }
+  }
+
+  // ── 调用方自带的核验方案：只允许产物级 ──
+  if (arg.proposedVerification !== undefined && arg.proposedVerification !== null) {
+    const pv = arg.proposedVerification
+    const ok =
+      pv && typeof pv === 'object' && !Array.isArray(pv) &&
+      pv.kind === 'artifact-content-hash' &&
+      Array.isArray(pv.checks) && pv.checks.length > 0 &&
+      pv.checks.every((c) => c && VERIFICATION_COMPARATORS.includes(c.comparator) && isContentHash(c.expectSha256))
+    if (!ok) {
+      return {
+        ...base,
+        code: 'E_PROCESS_ONLY_VERIFICATION',
+        reasons: ['proposedVerification 不是产物级核验（须 kind=artifact-content-hash、comparator=sha256-equal、每条 check 带 expectSha256）⇒ 只断言过程的方案抓不到空操作，拒绝'],
+      }
+    }
+  }
+
+  // ── 排序依据：优先 seq（全整数才算齐备），否则下标。时间戳永不参与。 ──
+  const allHaveSeq = history.length > 0 && history.every((h) => Number.isInteger(h?.seq))
+  const orderingBasis = allHaveSeq ? 'seq' : 'array-index'
+  if (!allHaveSeq && history.some((h) => Number.isInteger(h?.seq))) {
+    base.reasons.push('历史里 seq 不完整 ⇒ 退化为按输入数组下标排序（orderingBasis=array-index，不静默）')
+  }
+
+  // ── 逐候选判定 ──
+  const considered = []
+  const eligible = []
+  history.forEach((h, idx) => {
+    const stateId = h && nonEmptyString(h.stateId) ? h.stateId : `(下标 ${idx})`
+    const reject = (code, reason) => considered.push({ stateId, hashes: {}, eligible: false, code, reason })
+    if (!h || typeof h !== 'object' || Array.isArray(h)) return reject('E_INPUT_SHAPE', '历史项不是对象')
+    // ① 可信性：verifiedGood + verifiedBy 二者缺一不可
+    if (h.verifiedGood !== true) return reject('E_TARGET_NOT_VERIFIED_GOOD', '未声明 verifiedGood=true ⇒ 不是已验证良好的状态')
+    if (!nonEmptyString(h.verifiedBy)) return reject('E_TARGET_NOT_VERIFIED_GOOD', 'verifiedGood=true 但没有 verifiedBy ⇒ "谁证明了它 good"缺失，未知 ≠ 已知良好')
+    const arts = tryArtifacts(h.artifacts)
+    if (arts === null) return reject('E_ARTIFACT_SET_MISMATCH', '产物缺合法内容哈希 ⇒ 无法核验，不能作为回退目标')
+    if (arts.length === 0) return reject('E_ARTIFACT_SET_MISMATCH', '产物列表为空 ⇒ 无可核验对象')
+    const hashes = hashesOf(arts)
+    // ② 必须覆盖故障态的全部产物（否则回退不彻底）
+    const missing = failureArtifacts.map((a) => a.name).filter((n) => !(n in hashes))
+    if (missing.length > 0) {
+      return considered.push({ stateId, hashes, eligible: false, code: 'E_ARTIFACT_SET_MISMATCH', reason: `未覆盖故障态产物 [${missing.join(', ')}] ⇒ 回退会不彻底，不予采纳` })
+    }
+    // ③ 全等 ⇒ 它不是一个"先前"状态，回退等于空操作
+    const identical = failureArtifacts.every((a) => hashes[a.name] === failureHashes[a.name])
+    if (identical) {
+      return considered.push({ stateId, hashes, eligible: false, code: 'E_ROLLBACK_NOOP', reason: '全部必需产物的哈希与故障态相同 ⇒ 回退到它等于空操作' })
+    }
+    const seq = allHaveSeq ? h.seq : idx
+    considered.push({ stateId, hashes, eligible: true, code: null, reason: null })
+    eligible.push({ stateId, seq, index: idx, artifacts: arts, hashes, refs: Array.isArray(h.evidenceRefs) ? h.evidenceRefs.filter(nonEmptyString) : [] })
+  })
+
+  const sortedConsidered = [...considered].sort((a, b) => (a.stateId < b.stateId ? -1 : a.stateId > b.stateId ? 1 : 0))
+  const evidence = { failureHashes, considered: sortedConsidered }
+
+  if (eligible.length === 0) {
+    return {
+      ...base,
+      evidence,
+      code: 'E_NO_ROLLBACK_TARGET',
+      reasons: [...base.reasons, `历史里 ${history.length} 个状态无一满足"已验证良好 + 有哈希背书 + 覆盖故障态全部产物" ⇒ 无回退目标，拒绝（不猜最近的那个）`],
+    }
+  }
+
+  // ④ 取"上一个"：seq 最大者；seq 相同按下标最大者（全序）
+  eligible.sort((a, b) => (a.seq !== b.seq ? b.seq - a.seq : b.index - a.index))
+  const pick = eligible[0]
+
+  const steps = failureArtifacts
+    .map((a) => ({ op: 'restore', artifact: a.name, from: pick.stateId, expectSha256: pick.hashes[a.name] }))
+    .sort((x, y) => (x.artifact < y.artifact ? -1 : x.artifact > y.artifact ? 1 : 0))
+
+  const checks = failureArtifacts
+    .map((a) => ({ artifact: a.name, expectSha256: pick.hashes[a.name], observedFrom: 'artifact-content-hash（回退后现场重算）', notBeforeSha256: failureHashes[a.name] }))
+    .sort((x, y) => (x.artifact < y.artifact ? -1 : x.artifact > y.artifact ? 1 : 0))
+
+  return {
+    ...base,
+    refused: false,
+    code: null,
+    target: { stateId: pick.stateId, seq: pick.seq, artifacts: jsonClone(pick.artifacts, 'target.artifacts') },
+    path: { kind: 'restore-artifacts', orderingBasis, steps },
+    verification: { kind: 'artifact-content-hash', comparator: 'sha256-equal', checks, criterion: VERIFICATION_CRITERION, rejectsProcessOnly: true },
+    reasons: [
+      ...base.reasons,
+      `回退目标 ${pick.stateId}（排序依据 ${orderingBasis}，seq=${pick.seq}；时间戳未参与决策）`,
+      `被排除的候选：${sortedConsidered.filter((c) => !c.eligible).map((c) => `${c.stateId}(${c.code})`).join(', ') || '无'}`,
+    ],
+    evidence,
+    evidenceRefs: uniqSorted([...refs, ...pick.refs]),
+  }
+}
+
+/**
+ * 核验回退是否**真的**生效（产物级）。
+ *
+ * @param {{decision:object, observed:object}} p
+ *   `observed` = **别处**产出的现场观测：`{ artifacts: [{name, sha256}], exitCode?, producedBy? }`。
+ *   只有过程证据（退出码/日志）而没有哈希 ⇒ 核验失败。
+ */
+export function verifyRollbackDecision({ decision, observed } = {}) {
+  const d = assertPlainObject(decision ?? null, 'decision', 'E_INPUT_SHAPE')
+  const o = assertPlainObject(observed ?? null, 'observed', 'E_INPUT_SHAPE')
+
+  if (o.producedBy === CAPABILITY_ID) {
+    return { ok: false, code: 'E_SELF_JUDGING', checks: [], reasons: [`observed.producedBy=${CAPABILITY_ID} ⇒ 用本能力的产物自证回退生效，不算证据`] }
+  }
+  if (!d || d.refused === true || !d.verification) {
+    return { ok: false, code: d?.code ?? 'E_NO_ROLLBACK_TARGET', checks: [], reasons: ['决策本身未产出回退方案（refused）⇒ 无可核验内容'] }
+  }
+
+  const obsArts = Array.isArray(o.artifacts) ? o.artifacts.filter((a) => a && nonEmptyString(a.name) && isContentHash(a.sha256)) : []
+  if (obsArts.length === 0) {
+    return {
+      ok: false,
+      code: 'E_PROCESS_ONLY_VERIFICATION',
+      checks: [],
+      reasons: ['observed 里没有任何带合法 sha256 的产物 ⇒ 只有过程证据（退出码/日志）⇒ 过程断言抓不到空操作，核验失败（这正是"回退失败"最隐蔽的形态）'],
+    }
+  }
+  const obsMap = hashesOf(obsArts)
+  const failureHashes = d.evidence?.failureHashes ?? {}
+  const considered = Array.isArray(d.evidence?.considered) ? d.evidence.considered : []
+
+  const checks = []
+  for (const c of d.verification.checks) {
+    const got = obsMap[c.artifact]
+    if (got === undefined) {
+      checks.push({ artifact: c.artifact, expect: c.expectSha256, observed: null, ok: false, code: 'E_ROLLBACK_INCOMPLETE', reason: '未观测到该产物的哈希 ⇒ 回退不彻底（无法证明它回到目标版本）' })
+      continue
+    }
+    if (got === c.notBeforeSha256) {
+      checks.push({ artifact: c.artifact, expect: c.expectSha256, observed: got, ok: false, code: 'E_ROLLBACK_NOOP', reason: '哈希与回退前完全相同 ⇒ 空操作，回退未生效' })
+      continue
+    }
+    if (got !== c.expectSha256) {
+      const owner = considered.find((s) => s.hashes && s.hashes[c.artifact] === got)
+      checks.push({
+        artifact: c.artifact,
+        expect: c.expectSha256,
+        observed: got,
+        ok: false,
+        code: 'E_ROLLBACK_WRONG_VERSION',
+        reason: owner ? `观测到的哈希属于历史状态 ${owner.stateId} ⇒ 回退到了错误版本` : '观测到的哈希既不是目标版本也不是回退前版本 ⇒ 回退到了未知版本',
+      })
+      continue
+    }
+    checks.push({ artifact: c.artifact, expect: c.expectSha256, observed: got, ok: true, code: null, reason: null })
+  }
+
+  const failed = checks.filter((x) => !x.ok)
+  if (failed.length === 0) {
+    return { ok: true, code: null, checks, reasons: [`全部 ${checks.length} 个产物的 sha256 与目标状态一致 ⇒ 回退在产物层面生效（依据：${VERIFICATION_CRITERION}）`] }
+  }
+  return { ok: false, code: failed[0].code, checks, reasons: failed.map((f) => `${f.code}: ${f.artifact} —— ${f.reason}`) }
+}
+
+function tryArtifacts(list) {
+  const arr = optionalArray(list, 'artifacts', 'E_INPUT_SHAPE')
+  const out = []
+  for (const a of arr) {
+    if (!a || typeof a !== 'object' || Array.isArray(a)) return null
+    if (!nonEmptyString(a.name) || !isContentHash(a.sha256)) return null
+    out.push({ name: a.name, sha256: a.sha256 })
+  }
+  return out
+}
+
+function collectArtifacts(list) {
+  const arr = optionalArray(list, 'failure.artifacts', 'E_INPUT_SHAPE')
+  const out = []
+  for (const a of arr) {
+    if (!a || typeof a !== 'object' || Array.isArray(a)) continue
+    if (!nonEmptyString(a.name) || !isContentHash(a.sha256)) continue
+    out.push({ name: a.name, sha256: a.sha256 })
+  }
+  return out
+}
+
+function hashesOf(arts) {
+  const h = {}
+  for (const a of arts) h[a.name] = a.sha256
+  return h
+}

package/src/support.mjs

@@ -0,0 +1,198 @@
+/**
+ * support.mjs —— 纯函数支撑层（类型守卫 / 规范化 JSON / 确定性排序 / 小统计）。
+ *
+ * 三条纪律（沿用 state-core 的方言约定与四个插件的既有口径）：
+ *   ① **零运行时依赖**：不 import 任何包，也不用 `node:*`。需要文件系统时**注入**，
+ *      不在本层自行 import（见 state-core/src/dialect.mjs 的做法）。
+ *   ② **不猜**：形状不对就响亮抛错（`RsiLoopError` + 稳定 code），不静默归一。
+ *   ③ **确定性**：本层不引入任何时间、随机、环境相关量。排序一律是**全序**（有唯一 tiebreak），
+ *      否则同一输入的输出顺序会随运行时漂移。
+ */
+
+/** 本层的错误类型：带**稳定 code**，使调用方能按 code 分支而不是按 message 文本。 */
+export class RsiLoopError extends Error {
+  constructor(code, message, details = null) {
+    super(message)
+    this.name = 'RsiLoopError'
+    this.code = code
+    this.details = details
+  }
+}
+
+/** 方向词表（判定改进时用它归一符号；两个词表之外的值一律拒绝）。 */
+export const DIRECTIONS = Object.freeze(['higher-is-better', 'lower-is-better'])
+
+export function isPlainObject(v) {
+  if (v === null || typeof v !== 'object' || Array.isArray(v)) return false
+  const proto = Object.getPrototypeOf(v)
+  return proto === Object.prototype || proto === null
+}
+
+/** 结构性输入错误 → 抛错（数据性缺失 → 由各能力返回 refused/blocked 结果，不抛）。 */
+export function assertPlainObject(v, name, code) {
+  if (!isPlainObject(v)) throw new RsiLoopError(code, `${name} 必须是普通对象（实得 ${describe(v)}）`)
+  return v
+}
+
+export function assertArray(v, name, code) {
+  if (!Array.isArray(v)) throw new RsiLoopError(code, `${name} 必须是数组（实得 ${describe(v)}）`)
+  return v
+}
+
+function describe(v) {
+  if (v === null) return 'null'
+  if (Array.isArray(v)) return `array(${v.length})`
+  return typeof v
+}
+
+/** 有限数判定 —— NaN / ±Infinity / 数字样字符串**都不算**（后者是"没测出来"的伪装）。 */
+export function finiteNumber(v) {
+  return typeof v === 'number' && Number.isFinite(v)
+}
+
+export function nonEmptyString(v) {
+  return typeof v === 'string' && v.trim() !== ''
+}
+
+/** 内容哈希字面量（本仓库统一 `sha256:<64 hex>`；不认别的形态，含 `md5:`）。 */
+export function isContentHash(v) {
+  return typeof v === 'string' && /^sha256:[0-9a-f]{64}$/.test(v)
+}
+
+export function directionOf(v) {
+  return DIRECTIONS.includes(v) ? v : null
+}
+
+/** 改进量 = 沿"越好越对"的方向看，after 比 before 好多少（正数 = 变好）。 */
+export function improvementOf({ before, after, direction }) {
+  return direction === 'lower-is-better' ? before - after : after - before
+}
+
+export function mean(xs) {
+  if (!Array.isArray(xs) || xs.length === 0) return null
+  return xs.reduce((a, b) => a + b, 0) / xs.length
+}
+
+/** 中位数（偶数个取两中值平均）。**不排序入参**（不制造副作用）。 */
+export function median(xs) {
+  if (!Array.isArray(xs) || xs.length === 0) return null
+  const s = [...xs].sort((a, b) => a - b)
+  const mid = Math.floor(s.length / 2)
+  return s.length % 2 === 1 ? s[mid] : (s[mid - 1] + s[mid]) / 2
+}
+
+export function uniqSorted(xs) {
+  return [...new Set(xs)].sort()
+}
+
+/**
+ * 规范化 JSON 文本 —— **确定性序列化**（对象键按码点排序，数组保序）。
+ *
+ * 存在的理由：`JSON.stringify` 的键序取决于**对象构造顺序**，
+ * 于是"同一输入两次运行输出是否相同"会被无关的构造顺序污染。
+ * 本库的确定性断言用它做指纹，不用 `JSON.stringify`。
+ * 非有限数一律抛错（`NaN`/`Infinity` 不是 JSON，静默写成 `null` 就是伪造证据）。
+ */
+export function canonicalJson(value) {
+  return write(value, new Set())
+
+  function write(v, seen) {
+    if (v === null) return 'null'
+    const t = typeof v
+    if (t === 'boolean') return v ? 'true' : 'false'
+    if (t === 'number') {
+      if (!Number.isFinite(v)) throw new RsiLoopError('E_NON_FINITE_NUMBER', `规范化 JSON 拒绝非有限数：${String(v)}`)
+      return Object.is(v, -0) ? '0' : JSON.stringify(v)
+    }
+    if (t === 'string') return JSON.stringify(v)
+    if (t === 'function' || t === 'symbol' || t === 'bigint' || t === 'undefined') {
+      throw new RsiLoopError('E_NOT_JSON_SAFE', `规范化 JSON 拒绝 ${t} 值`)
+    }
+    if (seen.has(v)) throw new RsiLoopError('E_CYCLIC_REFERENCE', '规范化 JSON 检测到循环引用')
+    seen.add(v)
+    let out
+    if (Array.isArray(v)) out = `[${v.map((x) => write(x, seen)).join(',')}]`
+    else {
+      if (!isPlainObject(v)) throw new RsiLoopError('E_LIVE_OBJECT', `规范化 JSON 拒绝非普通对象（原型：${String(Object.getPrototypeOf(v)?.constructor?.name)}）—— 产物不得嵌入活对象`)
+      out = `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${write(v[k], seen)}`).join(',')}}`
+    }
+    seen.delete(v)
+    return out
+  }
+}
+
+/**
+ * 递归自证"可安全跨进程传输"：无函数 / 无 undefined / 无非有限数 / 无活对象 / 无环。
+ * 返回 `{ ok, violations[] }`（**不抛**，因为它的用途正是把违规**报出来**）。
+ */
+export function jsonSafeReport(value) {
+  const violations = []
+  const seen = new Set()
+  walk(value, '$')
+  return { ok: violations.length === 0, violations }
+
+  function walk(v, path) {
+    if (v === null) return
+    const t = typeof v
+    if (t === 'string' || t === 'boolean') return
+    if (t === 'number') {
+      if (!Number.isFinite(v)) violations.push(`${path}: 非有限数（${String(v)}）`)
+      return
+    }
+    if (t !== 'object') {
+      violations.push(`${path}: ${t} 值不是 JSON 类型`)
+      return
+    }
+    if (seen.has(v)) {
+      violations.push(`${path}: 循环引用`)
+      return
+    }
+    seen.add(v)
+    if (Array.isArray(v)) {
+      v.forEach((x, i) => walk(x, `${path}[${i}]`))
+    } else if (isPlainObject(v)) {
+      for (const k of Object.keys(v)) walk(v[k], `${path}.${k}`)
+    } else {
+      violations.push(`${path}: 活对象（原型 ${String(Object.getPrototypeOf(v)?.constructor?.name)}）`)
+    }
+    seen.delete(v)
+  }
+}
+
+/** 全序比较器：先按 `key` 升序，键相等时按 `tiebreak` 升序 —— 保证排序结果与输入顺序无关。 */export function compareBy(key, tiebreak) {
+  return (a, b) => {
+    const ka = key(a)
+    const kb = key(b)
+    if (ka < kb) return -1
+    if (ka > kb) return 1
+    const ta = tiebreak(a)
+    const tb = tiebreak(b)
+    if (ta < tb) return -1
+    if (ta > tb) return 1
+    return 0
+  }
+}
+
+/** 空数组/缺省都算"未声明"；非数组抛错（形状错误不静默当空）。 */
+export function optionalArray(v, name, code) {
+  if (v === undefined || v === null) return []
+  return assertArray(v, name, code)
+}
+
+/**
+ * 深拷贝并**同时**证明可 JSON 化 —— 产物里任何"活对象/函数/非有限数/环"都会在此抛错。
+ *
+ * 为什么用"拷贝"而不是"检查后原样透传"：透传会把调用方的对象**引用**放进产物，
+ * 调用方之后改它就会改历史证据（产物必须自持）。canonicalJson 既是校验器也是序列化器。
+ */
+export function jsonClone(value, name = 'value') {
+  try {
+    return JSON.parse(canonicalJson(value))
+  } catch (err) {
+    if (err instanceof RsiLoopError) {
+      throw new RsiLoopError(err.code, `${name} 不可安全 JSON 化：${err.message}`)
+    }
+    throw err
+  }
+}
+

package/src/version.mjs

@@ -0,0 +1,20 @@
+/**
+ * version.mjs —— 版本号的唯一定义处（单独成文件是为了避免能力实现与契约面互相 import 成环）。
+ *
+ * 两个版本号语义不同，**不要合并**：
+ *   - `CONTRACT_VERSION`：本库**导出面**的版本（五个能力的函数签名与错误码 v0 冻结面）。major 变更须暂停报告。
+ *   - `CAPABILITY_VERSION`：五个能力**语义**的版本（判据/失败模式清单的版本）。它进每一份产物，
+ *     使第三方能回答"这个结论是哪一版能力产出的"。任何能力语义变更都升它。
+ */
+
+/** 导出面版本（与兄弟库同名的 CONTRACT_VERSION 惯例一致）。 */
+export const CONTRACT_VERSION = '0.1.0'
+
+/** 能力语义版本（随每份产物返回）。
+ *
+ * **2.0.0（major，用户授权）**：`directionSelection` 的 `forbid-irreversible` 约束
+ * **改为把 `inPlace === true` 也算作不可逆**（与 `riskAssessment` 的自动注入判据对齐）。
+ * 1.x 语义下"声明了禁止不可逆、却选中就地变更手段"是**可能的**（已实测复现）；
+ * 旧语义经 `options.legacyForbidIrreversible=true` **完整保留**，供对照与回退。
+ */
+export const CAPABILITY_VERSION = '2.0.0'