RAN 协议
RAN 协议
Section titled “RAN 协议”RAN 协议 / RAN Protocol / Runtime Kernel 操作规范
1. 定位与边界
Section titled “1. 定位与边界”《RAN 协议》定义 RAN Runtime Kernel 的通用命令、事件、状态迁移、权限、审计、回放和版本治理。它不是行业业务协议；应用通过 Adapter/Port 提供领域规则和外部系统能力。
Kernel 的正式核心对象是《RAN 模型》定义的九类对象：Entity 实体、Identity 身份、Relationship 关系、Interaction 互动、Fact 事实、Inference 推断、Source 来源、Evidence 证据和 Event 事件。旧的 RanCredential、RanTrust、RanBond、RanAuthority 仅作为 Profile 协议保留。
2. 协议原则
Section titled “2. 协议原则”- 命令与事件分离：命令是请求意图，事件是 Kernel 接受后的已发生事实。
- 事件不可变：更正、撤回、失效通过新事件，不修改历史事件。
- 显式状态：状态迁移必须有前置条件、目标状态、依据、版本和审计。
- 可追溯：事实、推断、来源、证据和状态变化必须保留引用关系。
- 确定结果：重复、冲突、非法迁移、权限拒绝和外部未确认有固定结果。
- 版本固定：事件保存并在回放时使用记录时的 schema、rule 和 policy 版本。
- 应用隔离：应用不能直接写 Kernel canonical state，也不能把行业对象加入核心。
3. Command 契约
Section titled “3. Command 契约”每个命令至少包含：
| 字段 | 含义 |
|---|---|
command_id |
本次请求标识 |
command_type |
受支持的操作类型 |
actor_ref |
发起主体 |
subject_refs |
受影响资源引用 |
purpose |
使用目的 |
idempotency_key |
重试去重键 |
request_hash |
规范化请求哈希 |
expected_version |
乐观并发版本，可为空 |
payload |
命令参数和应用受控扩展 |
schema_version |
命令契约版本 |
policy_result |
allow、deny、mask 或 approval_required |
agent_control |
智能体能力、工具、风险、审批和降级声明，可选 |
同一 idempotency_key 只能对应一个 request_hash。相同键和相同哈希返回等价原结果；相同键和不同哈希返回 conflict。expected_version 不等于当前版本也返回 conflict。
4. CommandResult
Section titled “4. CommandResult”Kernel 返回以下固定状态：
| 状态 | 语义 | 是否产生领域事件 |
|---|---|---|
completed |
Kernel 已原子提交状态、事件和审计 | 是 |
rejected |
输入、权限、对象或状态约束失败 | 否 |
conflict |
幂等哈希或预期版本冲突 | 否 |
pending_review |
等待明确人工审批 | 否 |
accepted_async |
受控异步任务已接收但结果未完成 | 仅任务接受记录 |
unknown |
提交确认丢失，需幂等查询或对账 | 不得推测 |
失败不得留下部分状态。外部 Port 的投递失败不能把 rejected 或未确认写成 completed。
5. 通用命令与事件
Section titled “5. 通用命令与事件”| Command | 前置条件 | Accepted Event | 状态/结果 |
|---|---|---|---|
create_entity |
标识未使用，版本为 0 | EntityCreated |
实体 active |
declare_identity |
实体存在，身份标识未使用 | IdentityDeclared |
身份进入声明状态 |
transition_identity |
身份存在，目标状态迁移合法 | IdentityStateChanged |
身份进入目标状态 |
create_relationship |
至少两个实体存在 | RelationshipCreated |
关系 proposed |
transition_relationship |
关系存在，目标迁移合法 | RelationshipStateChanged |
关系进入目标状态 |
record_interaction |
当事方和来源存在 | InteractionRecorded |
追加互动，不自动成立关系 |
register_source |
来源标识未使用 | SourceRegistered |
来源 active |
record_evidence |
来源存在且摘要存在 | EvidenceRecorded |
证据 active |
record_fact |
至少一个来源或证据存在 | FactRecorded |
事实 active |
record_inference |
至少一个事实或证据存在，规则版本明确 | InferenceRecorded |
推断 active |
invalidate_fact |
事实当前有效 | FactInvalidated |
事实 invalidated，依赖推断变 stale |
invalidate_evidence |
证据当前有效 | EvidenceInvalidated |
证据 invalidated，依赖推断变 stale |
5.1 关系状态迁移
Section titled “5.1 关系状态迁移”| 当前状态 | 允许目标状态 |
|---|---|
proposed |
active、under_review、closed |
active |
restricted、under_review、inactive、closed |
under_review |
active、restricted、closed |
inactive |
active、closed |
restricted |
under_review、closed |
应用可以增加业务前置条件，但不能跳过 Kernel 的权限、版本、审计和事件门禁。关系状态不会因为一个推断失效而被隐式修改；应用必须发起显式重新评估或迁移命令。
6. Event 契约
Section titled “6. Event 契约”每个接受事件至少包含：
event_id、event_type、occurred_at、producer、subject_refs、schema_version、causation_id、correlation_id、visibility、payload、resulting_version、rule_version 和 policy_version。
事件 payload 必须足以恢复规范化状态，或明确引用一个兼容的历史转换器。事件是回放输入，不是命令的别名。
标准处理流程为：
Command -> schema/object validation -> Policy and Agent Control gate -> expected_version and state transition check -> atomic state + accepted Event + Kernel Audit commit -> external outbox/message acknowledgement7. 事实链与失效
Section titled “7. 事实链与失效”Source -> Evidence -> Fact -> Inference \-> explicit transition requestFact、Inference、Source 和 Evidence 是独立对象。Inference 必须写入 basis_fact_refs、evidence_refs、rule_version、有效期和复核状态。证据更正、撤回或过期产生新事件；依赖推断变为 stale 或 invalidated，但不会覆盖事实、关系或历史。
8. Adapter / Port 边界
Section titled “8. Adapter / Port 边界”| Port | Kernel 责任 | Adapter/宿主责任 |
|---|---|---|
EventStorePort |
追加不可变事件、提供分页回放输入 | 持久化、条件写、备份和对账 |
AuditPort |
追加 Kernel 审计 | 审计查询授权、保留、脱敏和存储 |
PolicyPort |
校验并执行结构化授权结果 | 身份、组织角色、用途和业务授权判断 |
MessagePort |
在提交后发布事件或异步任务 | 投递、重试、去重、死信和补偿 |
ClockPort |
提供可测试时间 | 生产时钟和同步 |
首版不使用分布式事务。Kernel 内部状态、事件和审计在同一提交边界；外部写入通过 outbox/受控任务、确认、重试、补偿和对账。
Adapter 可以把任意应用对象映射到 Kernel 引用和扩展，但不得把应用字段写成 Kernel 核心语义。Kernel 不读取应用共享数据库，也不拥有应用用户、组织、收费和产品工作流。
9. 权限、审计与 Agent Control
Section titled “9. 权限、审计与 Agent Control”Policy 结果只能是 allow、deny、mask 或 approval_required：
allow：继续校验和提交；deny：返回rejected，不产生领域事件；mask：只允许策略声明的脱敏读取或受限动作；approval_required：返回pending_review，等待明确责任人批准。
Agent Control 至少记录 agent_ref、capability、tool_ref、risk_class、capability_version、approval_owner、required_permissions 和 fallback。高风险调用没有有效 approval_ref 不得执行。拒绝、超时、降级和人工决定都要进入追加审计。非 Agent 命令也可以直接进入 approval_required，由应用 ReviewTask 提供责任人。
Kernel 审计至少包含 audit_id、command_id、actor、purpose、resource、decision、policy_version、result、occurred_at 和关联事件引用。
10. 回放、冲突与版本治理
Section titled “10. 回放、冲突与版本治理”回放必须使用事件自身记录的 schema_version、rule_version 和 policy_version，不得使用当前规则重算历史结论。回放接口应支持分页、最大事件数/深度、时间范围、内存预算和取消信号；首版内存实现只验证语义，不承诺生产吞吐。
kernel.v0.x 可以增加可选字段和 extensions。删除必填字段、改变状态语义或改变事件解释必须升级主版本；历史事件原文和兼容转换记录必须保留。
11. Profile 协议
Section titled “11. Profile 协议”旧协议保留为 RAN 语义层 Profile：
RanCredential Protocol：围绕Identity、Evidence和核验事件组织身份 Profile；RanTrust Protocol：围绕带依据、上下文和有效期的Inference组织信任判断；RanBond Protocol：围绕Relationship、Interaction和状态事件组织关系 Profile；RanAuthority Protocol：围绕贡献事实、推断和治理事件组织贡献 Profile。
这些 Profile 不得改变 Kernel 九类对象的最小接口。
12. 一致性测试
Section titled “12. 一致性测试”Kernel 提供中立测试向量、合成 fixture 和 Adapter contract tests。两个独立 Adapter 使用不同的外部字段结构，但必须在创建实体、身份、关系、事实、推断、幂等、冲突、失效、回放、权限和 Agent Control 上得到相同 Kernel 语义。
可执行参考实现和向量见 docs/runtime-kernel/（内部材料未公开）。