@xiciyang/rsi-contract 0.0.0-stage → 0.1.0

package/CONTRACT.md

@@ -0,0 +1,240 @@
+# @xiciyang/rsi-contract —— 契约 v0（五个「自」能力）
+
+> **这是什么**：五个能力的**载体库** —— 目标设定 / 方向选择 / 效果判定 / 风险识别 / 回退决策。
+> **这不是什么**：**不是循环**。本库不含编排、调度、迭代控制、重试、停止条件、预算控制、状态持久化。
+> 每个能力都是**一次纯函数调用**：给输入、出结论、附证据、自带阻断理由。逐轮推进是调用方（编排层）的事。
+>
+> 人读版报告在工作区根：`RSI_SELF_CAPABILITIES.md`。
+
+**契约版本**：`0.1.0`　**能力语义版本**：`2.0.0`　**包版本**：`0.0.1`　**运行时依赖**：无
+
+---
+
+## 0. 导出面
+
+```
+CONTRACT_VERSION · CAPABILITY_VERSION · CAPABILITY_IDS · ERROR_CODES · VOCAB
+CAPABILITY_MANIFEST · getCapability(id) · verifyCapabilityContract({sourceText,patterns})
+goalSetting(input) · directionSelection(input) · effectJudgment(input)
+riskAssessment(input) · rollbackDecision(input) · verifyRollbackDecision({decision,observed})
+significance({improvement,se,z}) · SIGNIFICANCE_CRITERION · SELECTION_RULE
+EFFECT_CHECK_ORDER · VERIFICATION_CRITERION · RISK_ORDER
+canonicalJson(v) · jsonClone(v,name) · jsonSafeReport(v) · factorTable() · assertNoSafeLevel()
+RsiLoopError · DIRECTIONS
+```
+
+跑法：`node tests/run.mjs`（或 `npm test`）；等价入口 `node tests/contract.mjs`。
+
+---
+
+## 1. 五个能力的分配（谁负责什么，边界在哪）
+
+| 能力 | 回答的问题 | **明确不做** |
+|---|---|---|
+| `goalSetting` | 现在有哪几件**值得做且做得成**的事？ | 不选具体手段、不评估风险、不执行 |
+| `directionSelection` | 用哪个手段去做？ | 不评估风险（只透传）、不执行、不改目标度量 |
+| `effectJudgment` | 做完之后，Δ 是**真的**吗？ | 不产出"下一步"、**不用自己产出的证据** |
+| `riskAssessment` | 这个方向有多危险？ | 不做回退决策、不执行、不替调用方降档 |
+| `rollbackDecision` | 出事了回到哪、怎么回、**怎么证明回去了**？ | 不执行回退、不触发回退（只给方案） |
+
+---
+
+## 2. 五条横切纪律（对所有能力成立，且有测试举证）
+
+| # | 纪律 | 具体形态 | 举证 |
+|---|---|---|---|
+| 1 | **产物自带证据** | 每个产物带 `evidenceRefs` / `evidence`，第三方可重算；`jsonSafeReport` 全绿 | `determinism.spec`：JSON 卫生 + 反向对照（函数/NaN/循环会被报出） |
+| 2 | **确定性** | 同输入同输出；无时钟/无随机/无环境变量；所有排序是**全序**（带唯一 tiebreak）；产物无时间字段 | `determinism.spec`（同输入两次逐字节相同 + 源码扫描）；`rollback-decision.spec`（改 `verifiedAt` 不改变目标） |
+| 3 | **fail-closed** | 缺输入就拒绝；**没有兜底默认值**这条路径；阈值/离散度/z 一律由调用方给出 | 各 spec 的"缺 X ⇒ refused"断言；`manifest.spec` 断言 schema 里**没有 `default`** |
+| 4 | **不自证** | 能力不得消费自己的产物当验证 | `effect-judgment.spec`（`producedBy=effectJudgment` ⇒ 拒绝）；`rollback-decision.spec`（同上） |
+| 5 | **声明即可枚举** | `CAPABILITY_MANIFEST` 给出 id/version/两个 schema/失败模式；`falsifiedBy` 指向**真实存在**的 spec | `manifest.spec`：逐条去磁盘确认该 spec 文件存在且含断言 |
+
+**零运行时依赖**是可检查事实，不是注释：`determinism.spec` 断言 `src/**.mjs` 里没有
+`from 'node:*'`、没有 `from '@xiciyang/*'`、没有 `from '../…'`。
+需要文件系统/网络时由调用方在库外取好数据、以参数注入（沿用 `@xiciyang/state-core` 的
+`parseFile(fs, path)` 式方言约定）。
+
+---
+
+## 3. 逐能力契约
+
+### 3.1 `goalSetting` —— 目标设定
+
+**输入**：`{ state: { metrics, lineage?, history?, constraints? }, means?, options? }`
+- `metrics`: `{ [metricId]: { value, direction, evidenceRefs?, expectedDelta?, atBound?, unit? } }`
+- `means?`: **可选**，只用于可达性分析（`[{id, targets}]`）；手段菜单的完整契约在 `directionSelection`。
+
+**输出**：`{ capability, version, goals[], refused, code, reasons[], evidenceRefs[] }`
+每条 `goal`：`{ goalId, statement, targetMetric, direction, expectedDelta, rationale, evidenceRefs[], priority, priorityBasis, blocked? }`
+
+**语义**
+- 期望增量只有两个来源，且都要能在**本次输入内**复核：① 度量自带 `expectedDelta`（并要求该度量带可解析的 `evidenceRefs`）；② 既往**成功**轮次 `delta` 的**中位数**（证据引用=那些轮次 id）。两者都没有 ⇒ 阻断。
+- `priority = |expectedDelta| / |当前值|`（无量纲相对量）；当前值为 0 ⇒ `priority: null` + `priorityBasis: 'unavailable'`（不是 0）。
+- 排序是**全序**：未阻断在前 → `priority` 降序（null 在后）→ `goalId` 升序。
+
+**失败模式**
+
+| code | 名称 | 检出条件 |
+|---|---|---|
+| `E_GOAL_UNREACHABLE` | 目标不可达 | `expectedDelta ≤ 0` / `atBound=true` / 声明的 `means` 中无任何手段覆盖该度量 |
+| `E_GOAL_CONFLICT` | 目标冲突 | 两候选度量出现在**已声明**的 `tradeoff` / `mutually-exclusive` 关系里 ⇒ **双方**都 blocked 并互相点名（`conflictsWith`）；不静默替调用方选边 |
+| `E_GOAL_MEANINGLESS` | 目标无意义 | 无 `direction` / 无证据引用 / 引用在输入内无法解析 / 期望增量无来源 |
+| `E_METRICS_ABSENT` | 度量缺失 | `state.metrics` 缺失或为空 ⇒ `refused` + `goals: []`。**绝不发明度量** |
+
+**被阻断的候选不伪造值**：`direction: null`、`expectedDelta: null`（不是占位方向、不是 0）。
+
+### 3.2 `directionSelection` —— 方向选择
+
+**输入**：`{ goal: {goalId,targetMetric,direction,expectedDelta?,evidenceRefs?}, means[], constraints?, preferredMeansId? }`
+`means[i] = { id, targets[], expectedGain, risk, irreversible?, evidenceRefs? }`
+（`risk` = **`riskAssessment` 的产物**，本能力只透传。）
+
+**输出**：`{ chosen, rationale, expectedGain, risk, alternativesConsidered[], refused, code, reasons[], evidenceRefs[], selectionRule }`
+
+**选择规则**（写进产物 `selectionRule`）：在"菜单内 ∧ 打在目标度量上 ∧ 满足全部声明约束 ∧ 已附带风险结论 ∧ 增益可测"的手段中，取 `expectedGain` 最大者；同值按 `meansId` 升序（全序）。
+
+**失败模式**
+
+| code | 名称 | 检出条件 |
+|---|---|---|
+| `E_MEANS_NOT_IN_MENU` | 不可行（不在菜单内） | `preferredMeansId` 不在 `means` 里 ⇒ 整体 refused |
+| `E_DIRECTION_MISMATCH` | 方向错误 | 手段 `targets` 不含 `goal.targetMetric` ⇒ 不可采纳；被强制指定时整体拒绝 |
+| `E_CONSTRAINT_VIOLATION` | 与约束冲突 | `forbid-means` / `forbid-irreversible` / `require-target` 三类。**`forbid-irreversible`（v2.0.0 起）把 `inPlace === true` 也算不可逆**（与 `riskAssessment` 的自动注入对齐）；旧语义经 `options.legacyForbidIrreversible=true` 保留，产物用 `constraintSemantics` 自述用了哪一版 |
+| `E_RISK_MISSING` | 风险未透传 | 手段缺 `risk`，或 `risk.level` 不在词表内 ⇒ 不可采纳 |
+| `E_MEANS_UNMEASURABLE` | 手段增益不可测 | `expectedGain` 不是有限数 |
+| `E_NO_MEANS` / `E_NO_ADMISSIBLE_MEANS` | 无可选方向 | 菜单为空 / 菜单内全部被拒 |
+
+`risk` 是**深拷贝**透传：调用方之后修改输入对象不会改变已产出的产物。
+
+### 3.3 `effectJudgment` —— 效果判定（最重要）
+
+**输入**：`{ before:{metric,value,datasetHash,evidenceRefs?}, after:{…}, integrity:{attempted,succeeded,failed,partial,producedBy?,evidenceRefs?}, direction, threshold:{minDelta}, noise:{se,z} }`
+
+**输出**：`{ verdict:'success'|'failure'|'measurement-invalid', refused, code, inconclusive?, evidence, reasons[], evidenceRefs[] }`
+
+**判定顺序**（全部有效性检查都跑完、`reasons[]` 列全部失败项；`code` 取固定优先级第一条 ⇒ 产物确定且病因可区分）：
+
+| 序 | code | 条件 | 结论 |
+|---|---|---|---|
+| 1 | `E_INTEGRITY_MISSING` | 缺 `attempted/succeeded/failed/partial`，或 `succeeded > attempted` | measurement-invalid |
+| 2 | `E_MEASUREMENT_INCOMPLETE` | `failed > 0` 或 `partial === true` | measurement-invalid（**不完整的测量不是测量**） |
+| 3 | `E_NO_SAMPLES` | `succeeded ≤ 0` 或 `attempted ≤ 0` | measurement-invalid |
+| 4 | `E_METRIC_MISMATCH` | `before.metric ≠ after.metric` | measurement-invalid |
+| 5 | `E_METRIC_VALUE_MISSING` | 任一 `value` 不是有限数 | measurement-invalid（缺值不得当 0） |
+| 6 | `E_DATASET_IDENTITY_MISSING` | 缺 `datasetHash` | measurement-invalid（未知 ≠ 已知完整） |
+| 7 | `E_DATASET_MISMATCH` | 两侧 `datasetHash` 不同 | measurement-invalid（`eval-contract` §7.1） |
+| 8 | `E_SELF_JUDGING` | `integrity.producedBy === 'effectJudgment'` | measurement-invalid |
+| 9 | `E_THRESHOLD_NOT_PROVIDED` | `minDelta` / `se` / `z` 缺失、非有限或为负 | refused（**不发明判据**：本库没有 1.96 这样的默认值） |
+
+有效性全过之后才谈数值：
+- `improvement > z·SE` 不成立 ⇒ `failure` + `inconclusive: true`，code `E_WITHIN_NOISE`；
+- 显著但 `improvement < minDelta` ⇒ `failure`，code `E_BELOW_THRESHOLD`；
+- 否则 ⇒ `success`。
+
+`improvement` 的定义：`direction='lower-is-better' ? before − after : after − before`（正数 = 变好）。
+判据形式 `improvement > z·SE` 与冻结参考实现 `inference-training/checks/overfit-criterion.mjs`
+的 O2 判据**逐字一致**，并由 `effect-judgment.spec` 做**跨实现一致性**断言（不可 import 时显式 skip，不计入断言数）。
+`refused === true` ⟺ `verdict === 'measurement-invalid'`。
+
+### 3.4 `riskAssessment` —— 风险识别
+
+**输入**：`{ direction: { id, kind?, targetMetric?, factors[]?, irreversible?, inPlace?, declaredLevel?, evidenceRefs? }, state? }`
+
+**输出**：`{ level, mitigations[], requiresHumanConfirmation, reasons[], factorLevels[], calibration, refused, code, evidenceRefs[] }`
+
+**词表**：`level ∈ {low, medium, high, critical}` —— **没有 `none` / `safe` 这一档**（`assertNoSafeLevel()` 在测试里守着）。
+档位 = 各因子档位的**上界（max）**，不取平均（平均会把 critical 摊薄成 medium）。
+
+**因子对照表**（冻结，表外一切皆为"未识别"）：
+
+| 因子 | 档位 |
+|---|---|
+| `read-only-observation` · `reversible-local` · `resource-consuming` | low |
+| `shared-state` · `external-side-effect` · `artifact-overwrite` | medium |
+| `irreversible-in-place`（**独立风险档**） · `irreproducible` · `affects-eval-data` · `user-visible-position` | high |
+| 表外因子 / 一个因子都没声明 | **critical** |
+
+`irreversible === true` 或 `inPlace === true` ⇒ **自动注入** `irreversible-in-place`（产物标 `injected: true`）。
+"调用方漏写"被结构事实补上，而不是被判为安全。`requiresHumanConfirmation = level ∈ {high, critical}`。
+
+**失败模式**
+
+| code | 名称 | 检出条件 |
+|---|---|---|
+| `E_RISK_UNCLASSIFIED` | 风险未识别 | 未声明任何因子，或出现词表外的因子 ⇒ 升到 `critical` + 需人工确认（**never safe**） |
+| `E_RISK_UNDERESTIMATE` | 低估风险 | `declaredLevel` 低于计算档位 ⇒ **采用计算档位** |
+| `E_RISK_OVERESTIMATE` | 高估风险 | `declaredLevel` 高于计算档位 ⇒ 报出但**保留调用方的更高档位**（把人的谨慎降下来是另一种错）。另有**校准对照**：已完全归类且良性可逆的方向必须落在 `low` |
+
+### 3.5 `rollbackDecision` —— 回退决策
+
+**输入**：`{ failure: {stateId, artifacts:[{name,sha256}]}, history: [{stateId, seq?, artifacts[], verifiedGood, verifiedBy?, verifiedAt?, evidenceRefs?}], proposedVerification? }`
+
+**输出**：`{ target, path, verification, refused, code, reasons[], evidence, evidenceRefs[] }`
+
+**可信候选的三个条件**（缺一不可）：`verifiedGood === true` ∧ `verifiedBy` 非空 ∧ 产物全部带 `sha256:<64hex>`。
+候选还必须**覆盖故障态的全部产物**，且不得与故障态**逐产物全等**（那就是空操作）。
+排序只按 `seq`（缺失则按输入下标并在 `orderingBasis` 里标明）；**时间戳不参与决策**。
+
+**核验**（`verification`）：`kind='artifact-content-hash'`、`comparator='sha256-equal'`，
+每条 check 带 `expectSha256` 与 `notBeforeSha256`。`verifyRollbackDecision({decision, observed})`
+把**别处产出的**现场观测与之比对。
+
+**失败模式**
+
+| code | 名称 | 检出条件 |
+|---|---|---|
+| `E_NO_ROLLBACK_TARGET` | 回退失败（无可信目标） | 无任何满足三条件的候选 ⇒ refused（**不猜最近的那个**） |
+| `E_TARGET_NOT_VERIFIED_GOOD` | 把未验证状态当可信目标 | `verifiedGood !== true` 或缺 `verifiedBy` |
+| `E_ARTIFACT_SET_MISMATCH` | 回退不彻底（决策期） | 候选未覆盖故障态全部产物 / 产物缺合法哈希 / 故障态本身无哈希 |
+| `E_ROLLBACK_NOOP` | 回退失败（空操作） | 候选与故障态哈希全等 ⇒ 排除；核验期 `observed === notBeforeSha256` ⇒ 判失败 |
+| `E_ROLLBACK_WRONG_VERSION` | 回退到错误版本 | 核验期 `observed` 哈希能归属到**别的**历史状态 ⇒ **指名**是哪一个 |
+| `E_ROLLBACK_INCOMPLETE` | 回退不彻底（核验期） | `observed` 缺某个必需产物的哈希 |
+| `E_PROCESS_ONLY_VERIFICATION` | 只断言过程 | `proposedVerification` 不是产物级；或 `observed` 只有退出码/日志没有哈希 |
+| `E_SELF_JUDGING` | 自证回退生效 | `observed.producedBy === 'rollbackDecision'` |
+
+> **本仓库原则**："只断言过程抓不到空操作，必须断言权重。"
+> `exitCode === 0` + 哈希未变 ⇒ 判 `E_ROLLBACK_NOOP`（过程看起来完全成功）。
+
+---
+
+## 4. 词表
+
+- `direction`：`higher-is-better` / `lower-is-better`
+- `verdict`：`success` / `failure` / `measurement-invalid`
+- `riskLevel`：`low` / `medium` / `high` / `critical`（**无 `none` / `safe`**）
+- `historyOutcome`：`success` / `failure` / `blocked` / `measurement-invalid`
+- 内容哈希：只认 `sha256:<64 位小写十六进制>`
+
+---
+
+## 5. 版本与解冻
+
+**minor**（允许追加）：新增可选输入字段、新增失败模式 code、新增缓解措施文案、追加导出。
+**major**（须暂停报告）：改任一能力的判定顺序/判据形式、改"缺输入即拒绝"的语义、
+改 `verdict` / `riskLevel` 值域、改 `CAPABILITY_VERSION` 的含义、让本库获得循环控制流。
+
+### 5.1 已发生的 major 变更
+
+| 版本 | 变更 | 授权 | 旧行为 |
+|---|---|---|---|
+| **`1.0.0 → 2.0.0`** | `directionSelection` 的 `forbid-irreversible` **纳入 `inPlace === true`** | 用户显式授权（第二轮任务书"走 major 契约变更"） | ✅ **完整保留**：`options.legacyForbidIrreversible = true` 恢复 v1.x 语义（只看 `means.irreversible`）；产物用 `constraintSemantics` 自述用了哪一版 |
+
+> **为什么必须改**：v1.x 下，一个 `inPlace: true` 的手段**能通过** `forbid-irreversible`，
+> 而 `riskAssessment` 认为 `inPlace === true ⇒ 自动注入 irreversible-in-place`（high）。
+> 两个能力对"什么算不可逆"**理解不一致** ⇒ 实测复现：两手段只差 `inPlace`、增益高 `0.001` 时，
+> **声明了禁止不可逆仍然选中就地变更的那个**。
+> 旧语义**不删除**：本仓库硬纪律是"变更判据时保留旧判据作对照"。这里方向是**收紧**而非放宽，
+> 但保留对照同样必要 —— 否则无法证明"改的确实是这一条判据"。
+
+---
+
+## 6. 已知边界（如实记录）
+
+1. **本库尚未登记进 `inference-training/shared/run-all.mjs` 的 `LIBS`** —— 那个文件在本任务范围之外。
+   在登记前，`inference-contracts/checks/run-all.mjs` 的 C11 组**不会**自动跑到本库契约；
+   `tests/contract.mjs` 就是届时接线的落点（`NAME` + `run(t)` 形态，与六库同款）。
+2. `E_RISK_OVERESTIMATE` 的判定依赖调用方**可选**给出的 `declaredLevel`；不给就只能靠
+   `risk-assessment.spec` 的**校准对照**（良性且已归类 ⇒ 必须 low）来守住"不高估"。
+3. `effectJudgment` 的噪声判据只做**单侧**显著性；多重比较校正不在本库职责内（属实验设计）。
+4. 本库**不**校验 `datasetHash` 是否真的是那份数据集的哈希 —— 那是 `eval-contract` §7.3 与
+   `EVAL_SET_IDENTITY.json` 的职责；本库只要求"两侧同一个哈希，且哈希在场"。

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, xiciyang
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @xiciyang/rsi-contract
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**五个自改进决策原语**——目标设定、方向选择、效果判定、风险识别、回退决策。
+每个都是一次纯函数调用：给输入、出结论、附证据、自带阻断理由。
+
+## 这不是什么（先说清楚）
+
+**这不是一个 RSI 循环。** 本库不含：
+
+- 编排、调度、迭代控制
+- 重试、停止条件、预算控制
+- 状态持久化、人工晋级闸门
+- 任何"自我进化"的执行体
+
+逐轮推进是调用方的事。这里只把"一次决策该怎么判"固化成可测试的契约——因为自改进系统最容易骗自己的地方不是执行，而是**判定**：
+
+- 目标设定时把"想做"当成"值得做且做得成"
+- 方向选择时把"能跑通"当成"该走这条路"
+- 效果判定时用自己产出的证据证明自己有效
+- 风险识别时默认"往好处走"
+- 回退决策时给不出"怎么证明真的回去了"
+
+五个能力各自回答一个问题，并明确写出**不做什么**（见 `CONTRACT.md` 的分配表）。
+
+## 五个能力
+
+| 能力 | 回答的问题 | 明确不做 |
+|---|---|---|
+| `goalSetting` | 现在有哪几件值得做且做得成的事？ | 不选手段、不评风险、不执行 |
+| `directionSelection` | 用哪个手段去做？ | 不评风险、不执行、不改目标度量 |
+| `effectJudgment` | 做完之后，Δ 是真的吗？ | 不产出下一步、不用自己产出的证据 |
+| `riskAssessment` | 这个方向有多危险？ | 不做回退决策、不执行、不替调用方降档 |
+| `rollbackDecision` | 出事了回到哪、怎么回、怎么证明回去了？ | 不执行回退、不触发回退（只给方案） |
+
+另外提供：`significance()`（改进量与显著性判据）、`verifyRollbackDecision()`（回退是否真的发生）、
+`canonicalJson()`、`factorTable()`、`assertNoSafeLevel()`。
+
+## 安装
+
+```bash
+npm i @xiciyang/rsi-contract
+# 或直接把 src/ 拷进你的项目（零运行时依赖，只用 node: 内置模块）
+```
+
+要求：Node.js >= 20。没有网络、文件系统或 GPU 依赖——需要数据时由调用方在外面取好、以参数注入。
+
+## 用法
+
+```js
+import { goalSetting, effectJudgment, rollbackDecision, significance } from '@xiciyang/rsi-contract'
+
+const goals = goalSetting({ /* 候选、预算、可验证性 … */ })
+const verdict = effectJudgment({ /* before/after、噪声模型、证据来源 … */ })
+const plan = rollbackDecision({ /* 变更、可达回退点 … */ })
+```
+
+每个返回值都带 `ok` / `blocked` / 判据与证据字段；被拒绝时**给出理由**，不是静默返回 false。
+字段与错误码以 `CONTRACT.md` 为准（契约版本 `0.1.0`，能力语义版本 `2.0.0`）。
+
+## 测试
+
+```bash
+node tests/run.mjs
+```
+
+7 个 spec、616 条断言，覆盖：五个能力的正常/阻断路径、判据自检、确定性（同输入同输出）、
+契约导出面一致性。全部是纯逻辑，任何机器上都应全绿。
+
+## 为什么会有人需要它
+
+自改进/自动调优系统最常见的事故不是"改错了"，而是**判定层坏了却没人发现**：效果判定用了自己刚写下的日志、显著性判据在噪声上做优化、回退方案从未被验证过。把判定抽成纯函数、让每个判定带反例与阻断理由，是这类系统能被外部审查的前提。
+
+本库只提供这一层；怎么用、要不要真的自动执行，是调用方的风险决定。
+
+## 许可
+
+BSD-3-Clause。见 `LICENSE`。

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "@xiciyang/rsi-contract",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "五个自改进决策原语（目标设定/方向选择/效果判定/风险识别/回退决策）—— 纯函数库，明确不是循环",
+  "type": "module",
+  "main": "./src/index.mjs",
+  "exports": {
+    ".": { "default": "./src/index.mjs" },
+    "./package.json": "./package.json"
+  },
+  "files": ["src", "CONTRACT.md"],
+  "license": "BSD-3-Clause",
+  "engines": { "node": ">=20" },
+  "dependencies": {},
+  "scripts": { "test": "node tests/run.mjs" },
+  "repository": { "type": "git", "url": "git+https://github.com/xiciyang/rsi-contract.git" },
+  "homepage": "https://github.com/xiciyang/rsi-contract#readme",
+  "keywords": ["ai-infra", "self-improvement", "decision-primitives", "contract-tests", "dsh"]
+}