# Rill Runtime 独立产品与发布契约
RillML 仍然是可嵌入的 Rust 算法库；`rill-runtime` 是建立在它之上的独立本地推理产品。宿主应用只需要编译很小的 `rill-runtime-protocol`，不需要把 RillML 引擎链接进自身，因此 Runtime 和模型包都能脱离宿主应用单独更新。
## 产物
| `rill-ml` | 在线学习算法与状态原语 | Rust crate |
| `rill-runtime-protocol` | 稳定、严格、带版本的 JSON IPC 类型 | Rust crate |
| `rill-runtime` | 加载签名模型包并执行内置的通用线性回归推理 | 独立可执行文件 |
| `*.rillpack` | 模型定义、参数、校验和与 Ed25519 签名 | 独立模型包 |
| `stable-index.json` | Runtime/模型的版本、平台、URL、大小与 SHA-256 | Ed25519 签名发布索引 |
Runtime 使用 stdin/stdout 上的逐行 JSON。每条消息最大 1 MiB，未知字段、未知 API 版本、过长请求 ID 和不合法数值都会被拒绝。握手会返回 Runtime、模型包和能力版本，宿主必须先验证握手，再接受推理结果。
## 安全与回退
- `.rillpack` 只允许固定文件集合，拒绝路径穿越、重复文件、额外载荷、缺失校验和和未知发布密钥。
- 发布索引的签名覆盖每个二进制和模型包的 SHA-256、大小、版本、平台与 URL；更新器不信任裸网络响应。
- Runtime 更新与模型更新彼此独立，但都必须通过启动自检后才能切换为 `current`。
- 宿主应用使用同文件系统目录重命名完成 `staging → current`，保留一个 `rollback`；激活失败会自动恢复。
- macOS Runtime 除发布索引签名外还必须通过 `codesign --verify --strict`。
- Runtime 缺失、超时、崩溃、包损坏、API 不兼容、模型数据不足或候选误差没有胜过基线时，宿主继续使用确定性回退。
模型包保存经过签名的不可变参数；在线学习状态和具体业务语义由宿主应用管理。
发布的独立 Runtime 支持 `rillml.linearRegression.predict`，模型包含有限的
`weights` 与 `intercept`，请求输入为 `{"features": [...]}`。其他业务能力应由消费方
实现 `InvokeHandler` 并构建自己的 Runtime；无论使用哪种 handler，Runtime 都只允许
调用已签名 manifest 中声明的 capability。
## 本地开发
```bash
cargo build -p rill-runtime --bins
cargo test -p rill-runtime-protocol -p rill-runtime
```
创建模型包时，私钥种子只从环境变量读取：
```bash
export RILL_SIGNING_KEY_HEX='<32-byte Ed25519 seed as hex>'
cargo run -p rill-runtime --bin rill-pack -- create \
--manifest models/example-default/manifest.json \
--model models/example-default/model.json \
--output example.rillpack
```
调试版宿主应用可使用 `RILL_RUNTIME_PATH`、`RILL_MODEL_PACK_PATH` 和 `RILL_TRUST_KEY=key-id=public-key-hex` 指向本地构建；这些覆盖项只在 debug 构建中生效。
## 正式发布
`.github/workflows/release.yml` 在 `vX.Y.Z` 标签上执行完整的发布流程：
1. `cargo package --dry-run` 验证 crate 可发布；
2. 为 Linux、Windows、Intel macOS 和 Apple Silicon macOS 编译 `rill-runtime` 二进制；
3. 签名模型包与稳定索引；
4. 创建单个 GitHub Release，包含所有平台二进制、`.rillpack` 和 `stable-index.json`。
5. 将 `rill-ml`、`rill-runtime-protocol`、`rill-runtime` 发布到 crates.io。
工作流允许在部分发布失败后安全重跑：已经发布的 crate 会跳过，已经存在的版本
Release 会复用其不可变资产，并继续修复 `local-ai-stable` 索引指针。已发布的版本标签
不得移动或覆盖。
发布前必须配置：
- `RILL_SIGNING_KEY_HEX`：必须对应发布者内置的 Ed25519 公钥；RillML 示例使用 `rillml-examples-2026-001` 密钥对，生产部署应使用独立密钥对；
- `CARGO_REGISTRY_TOKEN`：crates.io 发布令牌；
- `APPLE_CERTIFICATE_P12_BASE64`、`APPLE_CERTIFICATE_PASSWORD`、`APPLE_SIGNING_IDENTITY`：macOS Developer ID 代码签名（未配置时 macOS 二进制照常构建，仅跳过 codesign）；
- 模型 manifest、workspace 版本与标签版本必须完全一致。
仓库不会保存或生成生产私钥，也不会把未签名的示例文件冒充正式发布。
