# S04 元数据 ## 职责与对象 类型和结构定义、版本、扩展与投影，不拥有业务实例值。 实例归属以[总体架构](../总体架构.md)为准；结构、状态和公开外壳分别引用数据模型与接口契约。 ## 公开接口 | 用例 | 输入责任 | 输出与后果 | |------|----------|------------| | register_type | 类型身份、粒度和已登记生命周期族 | 类型候选 | | publish_schema | 字段结构及兼容检查 | 不可变结构版本 | | compose_schema | 基础和作品扩展的明确版本 | 有效结构与哈希 | | validate_value | 有效结构、用途和候选值 | 结构问题与引用校验需求 | | project_fields | 结构、用途和受控授权摘要 | 允许字段与剔除原因 | | activate_binding | 被审结构、预期绑定和影响处理 | 结构绑定回执 | 所有接口在本模块的接口.py 暴露。输入输出类型由同一公开表面导出，外部不导入私有模型或 SQL。 ## 内部职责 | 文件 | 职责 | |------|------| | 接口.py | 元数据公开用例和可导入合同 | | 模型.py | 元数据稳定对象、外壳及内部状态 | | 存储.py | 元数据所属记录的 SQL 与版本读写 | | 类型登记.py | 类型、粒度、业务归属和生命周期族 | | 结构版本.py | 不可变结构发布、启用及固定读取 | | 扩展合成.py | 基础结构和只增不改的作品扩展 | | 字段校验.py | 类型、必填、枚举、嵌套和引用结构 | | 字段投影.py | 展示、编辑、检索、导出和 AI 用途 | | 变更影响.py | 兼容分类、受影响实例及升级要求 | | 内置导入.py | 内置种子幂等登记，保护已存在绑定和扩展 | 完整路径及运行模板见[目标文件清单](../项目目录与文件职责.md)。逐文件意图、边界与目标见[文件合同](../文件设计/后端-S04-元数据.md)。 ## 实现约束 - 保留基础字段、开放内容字段和同生命周期新类型；系统身份与原生绑定由代码登记。 - 基础版本与作品扩展合成可重复，不能随 active 指针变化重新解释历史数据。 - 结构校验与真实引用校验分工，后者由实例所属模块执行。 - 内置种子是发布输入；PG 保存生效版本，启动不覆盖作者扩展。 - 字段消费与结构/策略变更经同一类型级事务锁排序：消费持共享咨询锁，变更持排他咨询锁并保护实际更新行。评测账号只拥有元数据读取权限，不能为消费锁授予表写权限；多个类型按统一顺序保护，锁不跨模型网络调用。 ## 协作与失败 业务模块和 B09 消费；前端通过 owner 投影得到结构和值；结构变更使用 S01 保护。 不兼容变更返回转换要求；结构、投影和实例版本不同步时拒绝；未知处理器和越权字段拒绝。 ## 验收行为 - M01 新字段贯通。 - M02 新类型贯通。 - M03 扩展不能绕过保护。 - M04—M08 版本、用途、迁移与并发。 验收入口和替换条件见[迁移与验收](../迁移与验收.md)；这些条目是目标行为，不是已通过测试的声明。 ## 当前公开范围 当前接入只开放登记候选、发布结构版本、兼容检查，以及业务owner对既有绑定的读写。发布v2不会自动升级固定绑定v1的实例。已有对象在线升级、作品扩展发布及在线策略更新单独立项，本期不提供公共启用工作流；既有低层API保留内部兼容。当前projection_version和类型锁协议保持不变；未来升级需独立转换、审阅、当前绑定CAS和恢复验收。 已发布种子的字段说明也参与结构内容哈希。`power_system`、`narrative_state` v1中的历史尾注是冻结说明，不是当前开发待办；本期保留原YAML字节。说明修订须发布新结构版本，既有实例是否升级另按在线升级项目处理，不以清理注释名义重写同版本身份。