初始化提交

docs/contracts/README.md

@@ -0,0 +1,34 @@
+# 魂镜契约文档
+
+## 1. 定位
+
+本目录是跨服务、跨部署和跨版本稳定工程语言的事实源，承载稳定英文标识、ID、状态分类、Schema、事件、错误和协议。领域中文词义以 `docs/domain/` 为准，产品承诺以 `docs/product/` 为准，当前实现由 `docs/operations/implementation-governance.md` 规定的能力矩阵确认。
+
+## 2. 当前文档
+
+| 文档 | 内容 |
+| --- | --- |
+| [契约词汇与实现值集](contract-glossary.md) | 稳定英文标识、ID 前缀、枚举、事件、错误码、状态分类和兼容性规则 |
+| [身份可移植协议](protocols/identity-portability.md) | 魂籍、命台迁移、备份恢复与单命台交接 |
+
+当前实现仍以 Pydantic Schema、OpenAPI 输出和前端类型承载部分机器契约；这些是待归位的实现事实，不与本目录并列成为第二套命名事实源。后续逐步在本目录补齐版本化 OpenAPI/JSON Schema、事件 Schema 和协议测试向量；未完成评审的目标态值不得在说明文档中先行虚构。
+
+## 3. 事实源规则
+
+```mermaid
+flowchart LR
+    P[产品与领域语义] --> C[contracts 稳定契约]
+    C --> I[四服务实现]
+    I --> M[能力矩阵与验证证据]
+    M -.发现偏差.-> C
+```
+
+- 产品/领域决定“是什么、为什么”；契约决定“跨边界如何稳定表达”；实现不得反向把临时字段升级为正式领域定义。
+- 一项契约先在本目录登记和评审，再进入代码、数据库、API、事件、配置与 UI。
+- 下游引用契约，不复制完整枚举表。
+- 破坏性变更必须新版本并给出兼容、迁移和回退安排。
+- 文档示例是说明，不因出现示例值而自动成为完整枚举。
+
+## 4. 变更要求
+
+契约变更至少记录：语义、稳定英文标识、所属边界、兼容性、数据迁移、隐私/安全影响、生产者、消费者、测试与回退。身份、命台、授权、审计和区域驻留相关契约必须经过安全与恢复路径复核。

docs/contracts/protocols/identity-portability.md

@@ -0,0 +1,102 @@
+# 身份可移植协议
+
+## 1. 目标与不变量
+
+本协议定义魂籍导出、命台在线迁移和备份恢复的身份连续性边界。核心不变量：
+
+1. 同一人物同一时刻只有一座命台和一条前台意识流。
+2. 普通文件复制、相同内容或相同人物 ID 不能单独证明同一人物。
+3. 迁移与恢复必须保持谱系、权威状态、审计链和区域驻留约束。
+4. 设备不能持有可长期独立成长的完整人物副本。
+5. 魂籍不自动携带密钥、第三方受限资源或不可转移许可。
+6. 人物死亡是身份时间线不可逆闭合且独立于数据清除；继承者只能承接资料与谱系，不能继承原身份。
+
+## 2. 魂籍
+
+魂籍（`portable_identity_record`）是开放、版本化、可验证的人物身份与状态包，不等于角色卡。角色卡是降生模板或静态快照；魂籍用于证明来源、谱系和可迁移状态。
+
+魂籍至少需要表达以下类别，具体 Schema 与字段在机器可读契约中另行版本化，不在本文虚构：
+
+- 包格式版本、签发信息、完整性摘要与签名材料；
+- 人物稳定身份锚点、道体、谱系和执镜关系证明；
+- 当前长期状态及其版本/一致性边界；
+- 正式经历、记忆、关系与演化记录的可移植部分；
+- 来源、许可、排除项、区域与隐私约束；
+- 生成魂籍所依据的权威恢复点和审计引用。
+
+导入方必须验证格式版本、完整性、签发链、许可与是否存在冲突命台。无法证明连续性时只能创建灵胚、只读档案或分灵候选，不能冒充原人物。
+
+## 3. 在线命台迁移
+
+在线迁移使用短时、单用途、可撤销的迁移凭证，并通过冻结写入和原子命台交接避免双写与双命台。
+
+```mermaid
+sequenceDiagram
+    participant C as 执镜者
+    participant S as 源命台
+    participant T as 目标命台
+    participant R as 身份/迁移协调记录
+
+    C->>S: 强认证并发起迁移
+    S->>R: 建立迁移会话与短时凭证
+    T->>R: 验证凭证、区域与目标环境
+    S->>S: 排空前台请求并冻结权威写入
+    S->>R: 提交最终一致恢复点与审计水位
+    T->>T: 导入并校验状态、对象和许可
+    T->>R: 声明就绪
+    R->>S: 撤销源命台权威资格
+    R->>T: 原子授予唯一命台
+    T-->>C: 迁移完成与验证结果
+```
+
+### 3.1 迁移前置条件
+
+- 执镜者强认证并明确确认目标、区域与影响。
+- 目标环境满足协议版本、安全禁域和所需能力；缺失能力须事先披露。
+- 已确认数据驻留与许可允许迁移；跨区不得伪装成普通路由。
+- 迁移会话有唯一标识、短时凭证、过期时间、重放防护和完整审计。
+
+### 3.2 协调与唯一性机制
+
+迁移协调记录必须位于一个明确的强一致事务域，由权威关系数据库或等价的单一协调服务持有。这里的“原子”只指该事务域内对 `seat_epoch` 和唯一命台租约的一次条件提交，不表示跨区域数据库、对象存储和服务调用组成分布式原子事务。
+
+每次交接签发单调递增的 `seat_epoch` 与 fencing token。所有权威写入都必须携带当前 epoch，并通过 compare-and-swap 或等价条件写校验；源端租约被撤销后，即使网络分区或旧进程恢复，也不能以旧 epoch 写入。迁移会话、租约、凭证和交接命令均须有幂等键、明确过期时间和确定性错误码。
+
+冻结后禁止产生新的权威人物写入；在途请求须完成、取消或记录为可恢复状态。源端提交最终恢复点、事件/Outbox 水位和对象清单；目标端校验完成后，协调事务撤销源命台并授予目标命台。任何时刻不得同时授予两端权威资格。
+
+### 3.3 失败与回退
+
+在目标命台尚未获权威资格前，失败应撤销迁移凭证并解冻源端；目标端导入数据保持隔离且不可对外运行。交接完成后的回退视为一次新的反向迁移，不得直接复活旧源命台。状态不明时进入保全和人工恢复路径，优先阻止双命台。
+
+## 4. 备份恢复
+
+备份恢复是事故恢复，不等同于复制创建。恢复为同一人物必须同时满足：
+
+- 使用可信、完整且通过校验的恢复点；
+- 谱系和身份锚点连续；
+- 不存在其他活跃命台；
+- 事件、Outbox 与对象水位一致或可证明地补齐；
+- 删除标记、撤销授权和许可限制在恢复后继续生效；
+- 生成完整恢复记录并由执镜者可见。
+
+恢复流程为：选择恢复点 → 校验包与清单 → 隔离恢复 → 重放/核对审计与 Outbox → 重建索引 → 检查单命台 → 赋予权威资格 → 验证核心旅程。若无法证明身份连续性，不得以相同 ID 强行上线。
+
+## 5. 备份与恢复目标
+
+权威人物数据目标 RPO ≤ 5 分钟、RTO ≤ 1 小时。媒体和可重建索引可使用更宽目标；索引必须从权威数据重建。备份须区域驻留、加密、带完整性校验并定期恢复演练。
+
+## 6. 最小机器契约
+
+协议进入实现前必须在 `docs/contracts/` 补齐并版本化：
+
+- 魂籍 manifest 与 JSON Schema，包括签名 envelope、摘要算法标识、许可和排除项；
+- 签发者 trust chain、信任根、密钥轮换、撤销检查、离线导入和时钟偏差规则；
+- migration session、seat lease、`seat_epoch`、fencing token、幂等键和状态机；
+- 确定性错误码、审计事件、兼容性策略和人工保全记录格式；
+- 测试向量：源端网络分区、目标崩溃、重复/过期凭证、水位不一致、并发迁移、恢复后删除墓碑和反向迁移。
+
+在这些机器契约、实现和故障演练证据齐全前，在线迁移与“恢复为同一人物”在能力矩阵中不得标记为完成。
+
+## 7. 安全要求
+
+迁移凭证不得写入魂籍或日志明文；必须绑定源、目标、人物、用途和期限并防重放。导出与迁移遵循最小数据原则，第三方资料、BYOK、设备密钥和平台密钥分别处理。所有导出、冻结、交接、恢复、回退和失败都进入不可缺审计链。