Runtime Kernel 集成指南

Kernel v0.1 集成指南

本文档是应用仓库接入 RAN Runtime Kernel 的工程入口。它只说明跨应用接入规则，不定义任何行业领域对象。

1. 接入顺序

每个应用仓库按以下顺序建立自己的 Adapter：

1. 固定应用到 Kernel 对象的映射表和外部 ID 命名空间。
2. 将应用写操作转换为 Command，禁止直接写 Kernel canonical state。
3. 实现应用自己的 EventStorePort、AuditPort、PolicyPort 和消息 outbox；首版不要求分布式事务。
4. 将 Kernel Event、CommandResult 和 Kernel Audit 投影回应用查询模型。
5. 使用合成数据运行全部 conformance vectors，再接入脱敏的应用 fixture。
6. 通过真实集成验收后，记录 Adapter、schema、rule、policy 和应用版本。

2. 应用侧必须拥有的内容

应用仓库负责：

• 领域对象、业务字段、业务状态和产品工作流；
• 用户、组织、角色、用途和数据访问授权；
• 外部系统 ID、持久化、消息投递、重试、死信和对账；
• 应用查询模型、UI、计费、运营和商业指标；
• 应用专属事实采集与行业规则，但推断仍必须映射为 Inference 并保留依据。

RAN 仓库不接受应用领域对象、真实个人数据、业务数据库 schema 或产品规则回写到 Kernel 核心。

3. 最小 Adapter 契约

Adapter 至少应提供以下映射能力：

能力	Kernel 输入	应用侧验收
创建实体	create_entity	外部 ID 可追溯且不可复用
声明/核验身份	declare_identity、transition_identity	身份声明与核验状态分离
建立/迁移关系	create_relationship、transition_relationship	参与方、上下文、状态和版本完整
记录互动	record_interaction	来源、时间和可见性完整
记录事实链	register_source、record_evidence、record_fact	原始事实不被模型输出覆盖
记录推断	record_inference	事实/证据、规则版本、有效期和复核状态完整
处理失效	invalidate_fact、invalidate_evidence	依赖推断进入 stale/invalidated，关系不隐式改写

4. Port 实现要求

• EventStorePort：不可变追加、条件版本写、分页读取和恢复对账。
• AuditPort：追加审计、查询授权、保留和脱敏；失败不得静默。
• PolicyPort：返回带 policy_version 的 allow、deny、mask 或 approval_required。
• MessagePort：只在 Kernel 内部提交成功后发布；采用 outbox、重试、去重和死信。
• ClockPort：生产环境提供 UTC 时间，测试环境提供可控时钟。

Port 的外部失败必须能区分 rejected、conflict、pending_review、accepted_async 和 unknown。应用不能因超时就重复写入一个新幂等键。

5. 版本与回放

应用必须保存每个接受事件的：

• schema_version；
• rule_version；
• policy_version；
• Adapter 版本和应用版本；
• 关联的 command_id、correlation_id 和外部事务/对账标识。

回放使用事件记录的历史版本，不使用当前业务规则重算历史结论。任何破坏性字段或状态语义变更必须升级 Kernel 主版本，并提供显式兼容转换器。

6. Conformance 提交包

应用接入 RAN 前应提交一份不含真实敏感数据的证据包：

• Adapter mapping table；
• Port implementation notes；
• 所有 conformance vectors 的结果；
• 幂等、版本冲突、非法迁移和部分失败证据；
• 事实/证据失效传播和回放等价性证据；
• 权限拒绝、人工审批、Agent Control 和审计证据；
• 数据保留、删除、更正和外部对账说明。

雁遇和雁达企鸣可以使用不同的应用字段和业务流程，但必须通过同一份 Kernel v0.1 契约。它们的业务对象和映射实现留在各自应用仓库。