@xiciyang/rsi-contract 0.0.0-stage → 0.1.0

package/src/contract.mjs

@@ -0,0 +1,890 @@
+/**
+ * contract.mjs —— **声明的契约面**：能力 id、错误码、I/O schema、失败模式、能力清单。
+ *
+ * 本文件是"机读契约"的唯一来源：`CAPABILITY_MANIFEST` 由它与各能力的实现现场组合而成，
+ * 而 CI 可以只 import 本文件就把五个能力的 schema 与失败模式枚举出来（不需要跑任何实现）。
+ *
+ * 纪律：
+ *   - 每一个 schema 都不写 `default`：**本库没有兜底默认值**（fail-closed 的正面要求）。
+ *   - 每一个失败模式都带 `falsifiedBy`：说明"哪条测试会让它变红"。
+ *     只声明不举证的失败模式等于没声明 —— 那是文档而不是契约。
+ */
+
+/** 九个错误码之外，本库还用 `E_*` 表示"拒绝"（refused）与"阻断"（blocked）。 */
+export const ERROR_CODES = Object.freeze({
+  // ── 结构性输入错误（抛 RsiLoopError） ──
+  E_INPUT_SHAPE: 'E_INPUT_SHAPE',
+  // ── 通用 fail-closed ──
+  E_METRICS_ABSENT: 'E_METRICS_ABSENT',
+  // ── goalSetting ──
+  E_GOAL_UNREACHABLE: 'E_GOAL_UNREACHABLE',
+  E_GOAL_CONFLICT: 'E_GOAL_CONFLICT',
+  E_GOAL_MEANINGLESS: 'E_GOAL_MEANINGLESS',
+  // ── directionSelection ──
+  E_DIRECTION_MISMATCH: 'E_DIRECTION_MISMATCH',
+  E_MEANS_NOT_IN_MENU: 'E_MEANS_NOT_IN_MENU',
+  E_CONSTRAINT_VIOLATION: 'E_CONSTRAINT_VIOLATION',
+  E_NO_MEANS: 'E_NO_MEANS',
+  E_NO_ADMISSIBLE_MEANS: 'E_NO_ADMISSIBLE_MEANS',
+  E_MEANS_UNMEASURABLE: 'E_MEANS_UNMEASURABLE',
+  E_RISK_MISSING: 'E_RISK_MISSING',
+  // ── effectJudgment ──
+  E_INTEGRITY_MISSING: 'E_INTEGRITY_MISSING',
+  E_MEASUREMENT_INCOMPLETE: 'E_MEASUREMENT_INCOMPLETE',
+  E_DATASET_IDENTITY_MISSING: 'E_DATASET_IDENTITY_MISSING',
+  E_DATASET_MISMATCH: 'E_DATASET_MISMATCH',
+  E_METRIC_MISMATCH: 'E_METRIC_MISMATCH',
+  E_METRIC_VALUE_MISSING: 'E_METRIC_VALUE_MISSING',
+  E_NO_SAMPLES: 'E_NO_SAMPLES',
+  E_THRESHOLD_NOT_PROVIDED: 'E_THRESHOLD_NOT_PROVIDED',
+  E_WITHIN_NOISE: 'E_WITHIN_NOISE',
+  E_BELOW_THRESHOLD: 'E_BELOW_THRESHOLD',
+  E_SELF_JUDGING: 'E_SELF_JUDGING',
+  // ── riskAssessment ──
+  E_RISK_UNCLASSIFIED: 'E_RISK_UNCLASSIFIED',
+  E_RISK_UNDERESTIMATE: 'E_RISK_UNDERESTIMATE',
+  E_RISK_OVERESTIMATE: 'E_RISK_OVERESTIMATE',
+  // ── rollbackDecision ──
+  E_NO_ROLLBACK_TARGET: 'E_NO_ROLLBACK_TARGET',
+  E_TARGET_NOT_VERIFIED_GOOD: 'E_TARGET_NOT_VERIFIED_GOOD',
+  E_ARTIFACT_SET_MISMATCH: 'E_ARTIFACT_SET_MISMATCH',
+  E_ROLLBACK_NOOP: 'E_ROLLBACK_NOOP',
+  E_PROCESS_ONLY_VERIFICATION: 'E_PROCESS_ONLY_VERIFICATION',
+  E_ROLLBACK_INCOMPLETE: 'E_ROLLBACK_INCOMPLETE',
+  E_ROLLBACK_WRONG_VERSION: 'E_ROLLBACK_WRONG_VERSION',
+  // ── JSON 卫生（support 层） ──
+  E_NOT_JSON_SAFE: 'E_NOT_JSON_SAFE',
+  E_CYCLIC_REFERENCE: 'E_CYCLIC_REFERENCE',
+  E_LIVE_OBJECT: 'E_LIVE_OBJECT',
+  E_NON_FINITE_NUMBER: 'E_NON_FINITE_NUMBER',
+})
+
+export const CAPABILITY_IDS = Object.freeze([
+  'goalSetting',
+  'directionSelection',
+  'effectJudgment',
+  'riskAssessment',
+  'rollbackDecision',
+])
+
+/** 值域词表（声明在契约里，实现不得私自定义第二份）。 */
+export const VOCAB = Object.freeze({
+  direction: ['higher-is-better', 'lower-is-better'],
+  verdict: ['success', 'failure', 'measurement-invalid'],
+  riskLevel: ['low', 'medium', 'high', 'critical'],
+  historyOutcome: ['success', 'failure', 'blocked', 'measurement-invalid'],
+})
+
+/** 回退核验的比较算子（只允许**内容哈希**比较；没有"退出码相等"这种算子）。 */
+export const VERIFICATION_COMPARATORS = Object.freeze(['sha256-equal'])
+
+const evidenceRefsSchema = {
+  type: 'array',
+  items: { type: 'string', minLength: 1 },
+  description: '可复核证据引用（度量 id / 血缘键 / 轮次 id）；必须能在输入内解析，否则该结论判为无证据',
+}
+
+/* ────────────────────────────── I/O SCHEMA ────────────────────────────── */
+/* 手写 JSON-Schema 子集（type / properties / required / additionalProperties / enum / items /
+   minLength / minimum）。不引任何 schema 库 —— 零依赖，且这里的形状是封闭的。 */
+
+const SCHEMAS = {
+  goalSetting: {
+    input: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['state'],
+      properties: {
+        state: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['metrics'],
+          properties: {
+            metrics: {
+              type: 'object',
+              description: '当前度量台账：键 = 度量 id。**缺失或为空 ⇒ 不发散任何自信目标（fail-closed）**',
+              additionalProperties: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['value', 'direction'],
+                properties: {
+                  value: { type: 'number' },
+                  direction: { type: 'string', enum: VOCAB.direction },
+                  evidenceRefs: evidenceRefsSchema,
+                  expectedDelta: {
+                    type: 'number',
+                    description: '沿 direction 的**改进量**（正数 = 变好）。≤0 ⇒ 不可达（按当前证据不比现状更好）',
+                  },
+                  atBound: { type: 'boolean', description: '已顶到该度量的边界 ⇒ 无余量 ⇒ 不可达' },
+                  unit: { type: 'string' },
+                },
+              },
+            },
+            lineage: { type: 'object', description: '血缘/来源引用：键 → 哈希或标识' },
+            history: {
+              type: 'array',
+              description: '既往轮次记录（期望增量的证据来源之一）',
+              items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['roundId', 'targetMetric', 'outcome'],
+                properties: {
+                  roundId: { type: 'string' },
+                  targetMetric: { type: 'string' },
+                  outcome: { type: 'string', enum: VOCAB.historyOutcome },
+                  delta: { type: 'number', description: '上一轮实测的改进量（正数 = 变好）' },
+                  evidenceRefs: evidenceRefsSchema,
+                },
+              },
+            },
+            constraints: {
+              type: 'array',
+              description: '声明的目标间耦合关系（冲突只能来自**已声明**的关系，不得凭猜测）',
+              items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['id', 'kind'],
+                properties: {
+                  id: { type: 'string' },
+                  kind: { type: 'string', enum: ['tradeoff', 'mutually-exclusive'] },
+                  between: { type: 'array', items: { type: 'string' } },
+                  note: { type: 'string' },
+                },
+              },
+            },
+          },
+        },
+        means: {
+          type: 'array',
+          description: '**可选**：可用手段菜单（只用于可达性分析；方向选择另有一份输入）',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['id', 'targets'],
+            properties: {
+              id: { type: 'string' },
+              targets: { type: 'array', items: { type: 'string' } },
+            },
+          },
+        },
+        options: {
+          type: 'object',
+          additionalProperties: false,
+          properties: { maxGoals: { type: 'integer', minimum: 0 } },
+        },
+      },
+    },
+    output: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['capability', 'version', 'goals', 'refused', 'code', 'reasons', 'evidenceRefs'],
+      properties: {
+        capability: { type: 'string', const: 'goalSetting' },
+        version: { type: 'string' },
+        goals: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['goalId', 'statement', 'targetMetric', 'direction', 'expectedDelta', 'rationale', 'evidenceRefs', 'priority', 'priorityBasis'],
+            properties: {
+              goalId: { type: 'string' },
+              statement: { type: 'string' },
+              targetMetric: { type: 'string' },
+              direction: { type: ['string', 'null'], description: '被阻断且无可测方向时为 null —— 不伪造占位值' },
+              expectedDelta: { type: ['number', 'null'], description: '无来源时为 null（不是 0）' },
+              rationale: { type: 'string' },
+              evidenceRefs: evidenceRefsSchema,
+              priority: { type: ['number', 'null'], description: '无量纲相对期望改进；无法归一 ⇒ null（不是 0）' },
+              priorityBasis: { type: 'string', enum: ['relative-to-current', 'unavailable'] },
+              blocked: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['code', 'reason'],
+                properties: {
+                  code: { type: 'string' },
+                  reason: { type: 'string' },
+                  conflictsWith: { type: 'array', items: { type: 'string' } },
+                },
+              },
+            },
+          },
+        },
+        refused: { type: 'boolean' },
+        code: { type: ['string', 'null'] },
+        reasons: { type: 'array', items: { type: 'string' } },
+        evidenceRefs: evidenceRefsSchema,
+      },
+    },
+  },
+
+  directionSelection: {
+    input: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['goal', 'means'],
+      properties: {
+        goal: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['goalId', 'targetMetric', 'direction'],
+          properties: {
+            goalId: { type: 'string' },
+            targetMetric: { type: 'string' },
+            direction: { type: 'string', enum: VOCAB.direction },
+            expectedDelta: { type: 'number' },
+            evidenceRefs: evidenceRefsSchema,
+          },
+        },
+        means: {
+          type: 'array',
+          description: '**声明的菜单**。不在其中的手段一律不可选（fail-closed）',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['id', 'targets', 'expectedGain', 'risk'],
+            properties: {
+              id: { type: 'string' },
+              targets: { type: 'array', items: { type: 'string' } },
+              expectedGain: { type: 'number' },
+              risk: { type: 'object', description: '**透传**：riskAssessment 的产物（本能力不自行评估风险）' },
+              irreversible: { type: 'boolean' },
+              evidenceRefs: evidenceRefsSchema,
+            },
+          },
+        },
+        constraints: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['id', 'kind'],
+            properties: {
+              id: { type: 'string' },
+              kind: { type: 'string', enum: ['forbid-means', 'forbid-irreversible', 'require-target'] },
+              meansId: { type: 'string' },
+              targets: { type: 'array', items: { type: 'string' } },
+              note: { type: 'string' },
+            },
+          },
+        },
+        preferredMeansId: { type: 'string', description: '调用方指定的手段：**若不在菜单内即拒绝**' },
+      },
+    },
+    output: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['capability', 'version', 'chosen', 'rationale', 'expectedGain', 'risk', 'alternativesConsidered', 'refused', 'code', 'reasons', 'evidenceRefs', 'selectionRule'],
+      properties: {
+        capability: { type: 'string', const: 'directionSelection' },
+        version: { type: 'string' },
+        chosen: {
+          type: ['object', 'null'],
+          additionalProperties: false,
+          required: ['meansId', 'targetMetric', 'direction', 'expectedGain'],
+          properties: {
+            meansId: { type: 'string' },
+            targetMetric: { type: 'string' },
+            direction: { type: 'string', enum: VOCAB.direction },
+            expectedGain: { type: 'number' },
+          },
+        },
+        rationale: { type: 'string' },
+        expectedGain: { type: ['number', 'null'] },
+        risk: { type: ['object', 'null'], description: '**透传**自所选手段的 risk 字段（本能力不生成风险结论）' },
+        alternativesConsidered: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['meansId', 'admissible', 'code', 'reason'],
+            properties: {
+              meansId: { type: 'string' },
+              admissible: { type: 'boolean' },
+              code: { type: ['string', 'null'] },
+              reason: { type: ['string', 'null'] },
+            },
+          },
+        },
+        refused: { type: 'boolean' },
+        code: { type: ['string', 'null'] },
+        reasons: { type: 'array', items: { type: 'string' } },
+        evidenceRefs: evidenceRefsSchema,
+        selectionRule: { type: 'string' },
+      },
+    },
+  },
+
+  effectJudgment: {
+    input: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['before', 'after', 'integrity', 'direction', 'threshold', 'noise'],
+      properties: {
+        before: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['metric', 'value', 'datasetHash'],
+          properties: {
+            metric: { type: 'string' },
+            value: { type: 'number' },
+            datasetHash: { type: 'string', description: '评估集内容哈希（eval-contract §7：Δ 只在同一 datasetHash 内可比）' },
+            evidenceRefs: evidenceRefsSchema,
+          },
+        },
+        after: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['metric', 'value', 'datasetHash'],
+          properties: {
+            metric: { type: 'string' },
+            value: { type: 'number' },
+            datasetHash: { type: 'string' },
+            evidenceRefs: evidenceRefsSchema,
+          },
+        },
+        integrity: {
+          type: 'object',
+          description: '**测量完整性必须由别处生产**（本能力不得自产自证）',
+          additionalProperties: false,
+          required: ['attempted', 'succeeded', 'failed', 'partial'],
+          properties: {
+            attempted: { type: 'number' },
+            succeeded: { type: 'number' },
+            failed: { type: 'number' },
+            partial: { type: 'boolean' },
+            producedBy: { type: 'string', description: '生产者标识；等于 effectJudgment 时判为自证（E_SELF_JUDGING）' },
+            evidenceRefs: evidenceRefsSchema,
+          },
+        },
+        direction: { type: 'string', enum: VOCAB.direction },
+        threshold: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['minDelta'],
+          properties: { minDelta: { type: 'number', description: '**必填且无默认值**：达标所需的最小改进量' } },
+        },
+        noise: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['se', 'z'],
+          properties: {
+            se: { type: 'number', description: '**必填且无默认值**：改进量的标准误（离散度）' },
+            z: { type: 'number', description: '**必填且无默认值**：显著性倍数（本库不硬编码 1.96）' },
+          },
+        },
+      },
+    },
+    output: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['capability', 'version', 'verdict', 'refused', 'code', 'evidence', 'reasons', 'evidenceRefs'],
+      properties: {
+        capability: { type: 'string', const: 'effectJudgment' },
+        version: { type: 'string' },
+        verdict: { type: 'string', enum: VOCAB.verdict },
+        refused: { type: 'boolean' },
+        code: { type: ['string', 'null'] },
+        inconclusive: { type: 'boolean' },
+        evidence: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['metric', 'direction', 'datasetHash', 'integrity', 'values'],
+          properties: {
+            metric: { type: ['string', 'null'] },
+            direction: { type: ['string', 'null'] },
+            datasetHash: { type: ['string', 'null'] },
+            integrity: { type: ['object', 'null'] },
+            values: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                before: { type: ['number', 'null'] },
+                after: { type: ['number', 'null'] },
+                improvement: { type: ['number', 'null'] },
+                minDelta: { type: ['number', 'null'] },
+                se: { type: ['number', 'null'] },
+                z: { type: ['number', 'null'] },
+                noiseBound: { type: ['number', 'null'] },
+                criterion: { type: ['string', 'null'] },
+              },
+            },
+          },
+        },
+        reasons: { type: 'array', items: { type: 'string' } },
+        evidenceRefs: evidenceRefsSchema,
+      },
+    },
+  },
+
+  riskAssessment: {
+    input: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['direction'],
+      properties: {
+        direction: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['id'],
+          properties: {
+            id: { type: 'string' },
+            kind: { type: 'string' },
+            targetMetric: { type: 'string' },
+            factors: {
+              type: 'array',
+              items: { type: 'string' },
+              description: '结构因子（已归类的风险事实）。**未声明任何因子 ⇒ 判为未识别 ⇒ 升到最高档**',
+            },
+            irreversible: { type: 'boolean' },
+            inPlace: { type: 'boolean', description: '就地变更（独立风险档）' },
+            declaredLevel: { type: 'string', enum: VOCAB.riskLevel, description: '调用方的自评档位；低于计算值 ⇒ 低估，高于 ⇒ 高估' },
+            evidenceRefs: evidenceRefsSchema,
+          },
+        },
+        state: { type: 'object', description: '系统状态（只读上下文；本能力不从中猜风险）' },
+      },
+    },
+    output: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['capability', 'version', 'level', 'mitigations', 'requiresHumanConfirmation', 'reasons', 'factorLevels', 'calibration', 'refused', 'code', 'evidenceRefs'],
+      properties: {
+        capability: { type: 'string', const: 'riskAssessment' },
+        version: { type: 'string' },
+        level: { type: 'string', enum: VOCAB.riskLevel },
+        mitigations: { type: 'array', items: { type: 'string' } },
+        requiresHumanConfirmation: { type: 'boolean' },
+        reasons: { type: 'array', items: { type: 'string' } },
+        factorLevels: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['factor', 'level', 'known', 'injected'],
+            properties: {
+              factor: { type: 'string' },
+              level: { type: 'string', enum: VOCAB.riskLevel },
+              known: { type: 'boolean' },
+              injected: { type: 'boolean', description: '由结构布尔（irreversible/inPlace）自动注入，而非调用方列举' },
+            },
+          },
+        },
+        calibration: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['declaredLevel', 'computedLevel', 'verdict'],
+          properties: {
+            declaredLevel: { type: ['string', 'null'] },
+            computedLevel: { type: 'string' },
+            verdict: { type: 'string', enum: ['consistent', 'underestimated', 'overestimated', 'undeclared'] },
+          },
+        },
+        refused: { type: 'boolean' },
+        code: { type: ['string', 'null'] },
+        evidenceRefs: evidenceRefsSchema,
+      },
+    },
+  },
+
+  rollbackDecision: {
+    input: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['failure', 'history'],
+      properties: {
+        failure: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['stateId', 'artifacts'],
+          properties: {
+            stateId: { type: 'string' },
+            artifacts: {
+              type: 'array',
+              items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['name', 'sha256'],
+                properties: { name: { type: 'string' }, sha256: { type: 'string' } },
+              },
+            },
+            evidenceRefs: evidenceRefsSchema,
+          },
+        },
+        history: {
+          type: 'array',
+          description: '已知的既往状态。**只有 verifiedGood 且有哈希背书的才算可信回退目标**',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['stateId', 'artifacts', 'verifiedGood'],
+            properties: {
+              stateId: { type: 'string' },
+              seq: { type: 'integer', description: '序号（唯一的排序依据；时间戳不参与决策）' },
+              artifacts: {
+                type: 'array',
+                items: {
+                  type: 'object',
+                  additionalProperties: false,
+                  required: ['name', 'sha256'],
+                  properties: { name: { type: 'string' }, sha256: { type: 'string' } },
+                },
+              },
+              verifiedGood: { type: 'boolean' },
+              verifiedBy: { type: 'string', description: '谁/什么证明了它 good；缺失 ⇒ 视为未验证' },
+              verifiedAt: { type: 'string', description: '仅记录，**不参与决策**' },
+              evidenceRefs: evidenceRefsSchema,
+            },
+          },
+        },
+        proposedVerification: {
+          type: 'object',
+          description: '调用方自带的核验方案；只断言过程的方案会被拒绝（E_PROCESS_ONLY_VERIFICATION）',
+          additionalProperties: true,
+        },
+      },
+    },
+    output: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['capability', 'version', 'target', 'path', 'verification', 'refused', 'code', 'reasons', 'evidence', 'evidenceRefs'],
+      properties: {
+        capability: { type: 'string', const: 'rollbackDecision' },
+        version: { type: 'string' },
+        target: {
+          type: ['object', 'null'],
+          additionalProperties: false,
+          required: ['stateId', 'seq', 'artifacts'],
+          properties: {
+            stateId: { type: 'string' },
+            seq: { type: 'integer' },
+            artifacts: { type: 'array', items: { type: 'object' } },
+          },
+        },
+        path: {
+          type: ['object', 'null'],
+          additionalProperties: false,
+          required: ['kind', 'orderingBasis', 'steps'],
+          properties: {
+            kind: { type: 'string', const: 'restore-artifacts' },
+            orderingBasis: { type: 'string', enum: ['seq', 'array-index'] },
+            steps: {
+              type: 'array',
+              items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['op', 'artifact', 'from', 'expectSha256'],
+                properties: {
+                  op: { type: 'string', const: 'restore' },
+                  artifact: { type: 'string' },
+                  from: { type: 'string' },
+                  expectSha256: { type: 'string' },
+                },
+              },
+            },
+          },
+        },
+        verification: {
+          type: ['object', 'null'],
+          additionalProperties: false,
+          required: ['kind', 'comparator', 'checks', 'criterion', 'rejectsProcessOnly'],
+          properties: {
+            kind: { type: 'string', const: 'artifact-content-hash' },
+            comparator: { type: 'string', enum: VERIFICATION_COMPARATORS },
+            checks: {
+              type: 'array',
+              items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['artifact', 'expectSha256', 'observedFrom', 'notBeforeSha256'],
+                properties: {
+                  artifact: { type: 'string' },
+                  expectSha256: { type: 'string' },
+                  observedFrom: { type: 'string' },
+                  notBeforeSha256: { type: 'string', description: '回退前的哈希：与 expect 相同即空操作，必须判失败' },
+                },
+              },
+            },
+            criterion: { type: 'string' },
+            rejectsProcessOnly: { type: 'boolean' },
+          },
+        },
+        refused: { type: 'boolean' },
+        code: { type: ['string', 'null'] },
+        reasons: { type: 'array', items: { type: 'string' } },
+        evidence: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['failureHashes', 'considered'],
+          properties: {
+            failureHashes: { type: 'object' },
+            considered: {
+              type: 'array',
+              items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['stateId', 'hashes', 'eligible', 'code', 'reason'],
+                properties: {
+                  stateId: { type: 'string' },
+                  hashes: { type: 'object', description: '该状态各产物的内容哈希（核验时用于把"未知版本"归属到具体状态）' },
+                  eligible: { type: 'boolean' },
+                  code: { type: ['string', 'null'] },
+                  reason: { type: ['string', 'null'] },
+                },
+              },
+            },
+          },
+        },
+        evidenceRefs: evidenceRefsSchema,
+      },
+    },
+  },
+}
+
+/* ────────────────────────── 失败模式（声明 + 举证） ────────────────────────── */
+
+const FAILURE_MODES = {
+  goalSetting: [
+    {
+      code: 'E_GOAL_UNREACHABLE',
+      name: '目标不可达',
+      detect: '期望改进量 ≤ 0 / 度量已顶到边界（atBound）/ 已声明手段菜单中无任何手段覆盖该度量 ⇒ 该候选 blocked',
+      falsifiedBy: 'unit/goal-setting.spec.mjs —— 「不可达必须 blocked，不得作为正常候选」',
+    },
+    {
+      code: 'E_GOAL_CONFLICT',
+      name: '目标冲突',
+      detect: '两候选的度量出现在**已声明**的 tradeoff / mutually-exclusive 关系中 ⇒ 冲突双方都 blocked 并互相点名（不静默替调用方选边）',
+      falsifiedBy: 'unit/goal-setting.spec.mjs —— 「已声明的冲突关系必须让双方 blocked 且 conflictsWith 非空」',
+    },
+    {
+      code: 'E_GOAL_MEANINGLESS',
+      name: '目标无意义',
+      detect: '缺可测目标（无 direction / 无期望增量来源）或无可解析的证据引用 ⇒ blocked',
+      falsifiedBy: 'unit/goal-setting.spec.mjs —— 「无证据引用 / 引用不可解析 ⇒ blocked」',
+    },
+    {
+      code: 'E_METRICS_ABSENT',
+      name: '度量缺失时不得发散自信目标',
+      detect: 'metrics 缺失或为空 ⇒ refused + goals: []（**绝不发明度量**）',
+      falsifiedBy: 'unit/goal-setting.spec.mjs —— 「缺度量 ⇒ 空目标 + refused」',
+    },
+  ],
+  directionSelection: [
+    {
+      code: 'E_DIRECTION_MISMATCH',
+      name: '方向错误',
+      detect: "所选手段的 targets 不含目标的 targetMetric ⇒ 该手段不可采纳；若被 preferredMeansId 强制指定则整体拒绝",
+      falsifiedBy: 'unit/direction-selection.spec.mjs —— 「手段不打目标度量 ⇒ 拒绝」',
+    },
+    {
+      code: 'E_MEANS_NOT_IN_MENU',
+      name: '不可行（不在声明的菜单内）',
+      detect: 'preferredMeansId 不在 means 菜单 ⇒ refused（fail-closed）',
+      falsifiedBy: 'unit/direction-selection.spec.mjs —— 「菜单外手段 ⇒ refused」',
+    },
+    {
+      code: 'E_CONSTRAINT_VIOLATION',
+      name: '与约束冲突',
+      detect: 'forbid-means / forbid-irreversible / require-target 三条约束被违反 ⇒ 该手段不可采纳',
+      falsifiedBy: 'unit/direction-selection.spec.mjs —— 「禁不可逆约束下不可逆手段不可采纳」',
+    },
+    {
+      code: 'E_RISK_MISSING',
+      name: '风险未透传',
+      detect: '手段缺 risk 字段 ⇒ 整体拒绝（选一个未评估风险的方向正是"风险未识别"的入口）',
+      falsifiedBy: 'unit/direction-selection.spec.mjs —— 「缺 risk ⇒ refused」',
+    },
+    {
+      code: 'E_MEANS_UNMEASURABLE',
+      name: '手段的期望增益不可测',
+      detect: 'expectedGain 不是有限数 ⇒ 该手段不可采纳（无收益数字的手段不得被选中）',
+      falsifiedBy: 'unit/direction-selection.spec.mjs —— 「expectedGain 缺失 ⇒ 不可采纳」',
+    },
+    {
+      code: 'E_NO_ADMISSIBLE_MEANS',
+      name: '菜单内无可采纳手段',
+      detect: '菜单非空但全部被拒 ⇒ refused（不是"随便挑一个"）',
+      falsifiedBy: 'unit/direction-selection.spec.mjs —— 「全部被拒 ⇒ refused 且逐条给出理由」',
+    },
+  ],
+  effectJudgment: [
+    {
+      code: 'E_MEASUREMENT_INCOMPLETE',
+      name: '测量不成立被忽略',
+      detect: 'integrity 缺字段 / failed > 0 / partial === true / succeeded === 0 ⇒ verdict = measurement-invalid（**永不 success**）',
+      falsifiedBy: 'unit/effect-judgment.spec.mjs —— 「failed=40 的截断测量必须 measurement-invalid」',
+    },
+    {
+      code: 'E_DATASET_MISMATCH',
+      name: '误判成功（跨评估集比较）',
+      detect: '两侧 datasetHash 不同或缺哈希 ⇒ measurement-invalid（eval-contract §7：Δ 只在同一 datasetHash 内可比）',
+      falsifiedBy: 'unit/effect-judgment.spec.mjs —— 「换评估集必须拒绝判定」',
+    },
+    {
+      code: 'E_WITHIN_NOISE',
+      name: '误判成功（噪声内）',
+      detect: 'improvement ≤ z·SE ⇒ failure + inconclusive（**永不 success**）',
+      falsifiedBy: 'unit/effect-judgment.spec.mjs —— 「改进落在噪声内 ⇒ 不得 success」',
+    },
+    {
+      code: 'E_THRESHOLD_NOT_PROVIDED',
+      name: '阈值缺失时不得自行发明判据',
+      detect: 'minDelta / se / z 任一缺失 ⇒ refused + measurement-invalid（本库不硬编码 1.96 之类的默认值）',
+      falsifiedBy: 'unit/effect-judgment.spec.mjs —— 「缺 z 或 SE ⇒ refused」',
+    },
+    {
+      code: 'E_SELF_JUDGING',
+      name: '自证',
+      detect: 'integrity.producedBy === "effectJudgment" ⇒ measurement-invalid',
+      falsifiedBy: 'unit/effect-judgment.spec.mjs —— 「自产的完整性证据必须被拒」',
+    },
+    {
+      code: 'E_BELOW_THRESHOLD',
+      name: '误判成功（未达阈值）',
+      detect: '显著但 improvement < minDelta ⇒ failure',
+      falsifiedBy: 'unit/effect-judgment.spec.mjs —— 「显著但未达阈值 ⇒ failure」',
+    },
+    {
+      code: 'E_METRIC_MISMATCH',
+      name: '比错了对象',
+      detect: 'before.metric ≠ after.metric ⇒ measurement-invalid（不同度量之间没有 Δ）',
+      falsifiedBy: 'unit/effect-judgment.spec.mjs —— 「前后不是同一个度量 ⇒ 拒绝」',
+    },
+    {
+      code: 'E_METRIC_VALUE_MISSING',
+      name: '测量值缺失被当成 0',
+      detect: 'before.value / after.value 不是有限数 ⇒ measurement-invalid（缺值不得当 0）',
+      falsifiedBy: 'unit/effect-judgment.spec.mjs —— 「缺 value ⇒ 拒绝，不得当 0」',
+    },
+    {
+      code: 'E_DATASET_IDENTITY_MISSING',
+      name: '评估集身份缺失',
+      detect: 'datasetHash 缺失/为空 ⇒ measurement-invalid（eval-contract §7.3：未知 ≠ 已知完整）',
+      falsifiedBy: 'unit/effect-judgment.spec.mjs —— 「缺 datasetHash ⇒ 拒绝判定」',
+    },
+  ],
+  riskAssessment: [
+    {
+      code: 'E_RISK_UNCLASSIFIED',
+      name: '风险未识别',
+      detect: '未声明任何因子 / 出现词表外的因子 ⇒ 升到 critical 且 requiresHumanConfirmation = true（**never safe**）',
+      falsifiedBy: 'unit/risk-assessment.spec.mjs —— 「未归类因子 ⇒ critical + 需人工确认」',
+    },
+    {
+      code: 'E_RISK_UNDERESTIMATE',
+      name: '低估风险',
+      detect: 'declaredLevel 低于计算档位 ⇒ 采用计算档位并报 underestimated',
+      falsifiedBy: 'unit/risk-assessment.spec.mjs —— 「自评 low 但含就地变更 ⇒ 升到 high 并报低估」',
+    },
+    {
+      code: 'E_RISK_OVERESTIMATE',
+      name: '高估风险',
+      detect: '良性且已完全归类的方向必须落在 low 档（校准对照）；实现若恒判 critical，该断言变红。declaredLevel 高于计算档位时保留调用方档位但报 overestimated',
+      falsifiedBy: 'unit/risk-assessment.spec.mjs —— 「只读/可逆本地 ⇒ 必须 low（不得高估）」',
+    },
+  ],
+  rollbackDecision: [
+    {
+      code: 'E_NO_ROLLBACK_TARGET',
+      name: '回退失败（无可信目标）',
+      detect: '没有任何"已验证良好 + 有哈希背书"的既往状态 ⇒ refused，不猜',
+      falsifiedBy: 'unit/rollback-decision.spec.mjs —— 「无 verifiedGood ⇒ refused」',
+    },
+    {
+      code: 'E_ROLLBACK_NOOP',
+      name: '回退失败（空操作）',
+      detect: '目标产物哈希与故障态相同 ⇒ 该候选不是回退目标；核验时 observed === notBefore ⇒ 判空操作',
+      falsifiedBy: 'unit/rollback-decision.spec.mjs —— 「只断言过程/哈希未变 ⇒ 判失败」',
+    },
+    {
+      code: 'E_ROLLBACK_WRONG_VERSION',
+      name: '回退到错误版本',
+      detect: 'observed 哈希等于**别的**历史状态 ⇒ verifyRollbackDecision 报错误版本',
+      falsifiedBy: 'unit/rollback-decision.spec.mjs —— 「回退到了另一个历史版本 ⇒ 指名报错」',
+    },
+    {
+      code: 'E_ROLLBACK_INCOMPLETE',
+      name: '回退不彻底',
+      detect: 'observed 缺某个必需产物的哈希 ⇒ 核验失败；候选若未覆盖故障态全部产物 ⇒ 决策期即排除',
+      falsifiedBy: 'unit/rollback-decision.spec.mjs —— 「只回退了一部分产物 ⇒ 判不彻底」',
+    },
+    {
+      code: 'E_PROCESS_ONLY_VERIFICATION',
+      name: '只断言过程（抓不到空操作）',
+      detect: 'proposedVerification 只含 process/exitCode 断言 ⇒ refused；observed 只有退出码无哈希 ⇒ 核验失败',
+      falsifiedBy: 'unit/rollback-decision.spec.mjs —— 「只断言过程的核验方案被拒」',
+    },
+    {
+      code: 'E_TARGET_NOT_VERIFIED_GOOD',
+      name: '把未验证状态当可信目标',
+      detect: 'verifiedGood !== true 或缺 verifiedBy ⇒ 不进入候选（"谁证明了它 good"缺失即未知）',
+      falsifiedBy: 'unit/rollback-decision.spec.mjs —— 「verifiedGood 无背书 ⇒ 候选被排除」',
+    },
+    {
+      code: 'E_ARTIFACT_SET_MISMATCH',
+      name: '回退不彻底（决策期）',
+      detect: '候选未覆盖故障态全部产物 / 产物缺合法内容哈希 / 故障态本身无哈希 ⇒ 排除或拒绝',
+      falsifiedBy: 'unit/rollback-decision.spec.mjs —— 「只覆盖一部分产物 ⇒ 排除该候选」',
+    },
+    {
+      code: 'E_SELF_JUDGING',
+      name: '自证回退生效',
+      detect: 'verifyRollbackDecision 的 observed.producedBy === "rollbackDecision" ⇒ 核验失败',
+      falsifiedBy: 'unit/rollback-decision.spec.mjs —— 「用本能力的产物自证 ⇒ 拒绝」',
+    },
+  ],
+}
+
+/**
+ * 组装**机读能力清单**：id / version / input schema / output schema / 声明的失败模式。
+ * CI 只需 import 本对象即可枚举五个能力（不需要执行实现）。
+ */
+export function buildManifest(capabilityVersion, implementations) {
+  return Object.freeze({
+    contractVersion: null, // 由 index.mjs 现场填入 CONTRACT_VERSION（避免循环 import）
+    capabilityVersion,
+    selfJudging: false,
+    capabilities: CAPABILITY_IDS.map((id) =>
+      Object.freeze({
+        id,
+        version: capabilityVersion,
+        implemented: typeof implementations?.[id] === 'function',
+        inputSchema: SCHEMAS[id].input,
+        outputSchema: SCHEMAS[id].output,
+        failureModes: FAILURE_MODES[id].map((m) => Object.freeze({ ...m })),
+      }),
+    ),
+  })
+}
+
+export function schemasFor(id) {
+  if (!CAPABILITY_IDS.includes(id)) throw new Error(`未知能力：${id}`)
+  return SCHEMAS[id]
+}
+
+export function failureModesFor(id) {
+  if (!CAPABILITY_IDS.includes(id)) throw new Error(`未知能力：${id}`)
+  return FAILURE_MODES[id]
+}
+
+/** 契约自检：每个能力都必须同时具备 id / 两个 schema / 实现 / 至少一条失败模式。 */
+export function assertManifestComplete(manifest) {
+  const problems = []
+  if (manifest.selfJudging !== false) problems.push('selfJudging 必须为 false')
+  const seen = new Set()
+  for (const c of manifest.capabilities) {
+    if (seen.has(c.id)) problems.push(`能力 id 重复：${c.id}`)
+    seen.add(c.id)
+    if (!c.implemented) problems.push(`${c.id}: 缺实现`)
+    if (c.inputSchema?.type !== 'object') problems.push(`${c.id}: 缺 inputSchema`)
+    if (c.outputSchema?.type !== 'object') problems.push(`${c.id}: 缺 outputSchema`)
+    if (!Array.isArray(c.failureModes) || c.failureModes.length === 0) problems.push(`${c.id}: 未声明失败模式`)
+    for (const m of c.failureModes ?? []) {
+      if (!m.code || !m.name || !m.detect || !m.falsifiedBy) problems.push(`${c.id}: 失败模式 ${m.code} 声明不完整（须含 code/name/detect/falsifiedBy）`)
+      if (m.falsifiedBy && !m.falsifiedBy.includes('.spec')) problems.push(`${c.id}: 失败模式 ${m.code} 未指向会变红的测试`)
+    }
+  }
+  for (const id of CAPABILITY_IDS) if (!seen.has(id)) problems.push(`清单缺能力：${id}`)
+  return { ok: problems.length === 0, problems }
+}