# 魂镜契约文档

## 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. 变更要求

契约变更至少记录：语义、稳定英文标识、所属边界、兼容性、数据迁移、隐私/安全影响、生产者、消费者、测试与回退。身份、命台、授权、审计和区域驻留相关契约必须经过安全与恢复路径复核。