附录 A —— Runtime 与集合 API 速查
本附录用于定位入口，不替代各章的语义、失败窗口和证据边界。API 以 DSM
505e7557 / 0.1.2 为准。
Runtime
| 动作 | 入口 | 关键约束 |
|---|---|---|
| 构建 | DsmRuntimeBuilder.builder() |
固定 clusterId、serviceId、membership
与安全/观测扩展 |
| 注册 Register | runtime.register(spec) |
在 start() 前完成；locator 不重复 |
| 注册 Lease | runtime.leaseRegister(spec) |
需要 codec、entity factory 与 Lease policy |
| 注册 CRDT | runtime.crdt(spec, merger) |
需要 update/state codec、initial state 与 merger |
| 启动 | runtime.start() |
registry freeze；成功后进入 RUNNING |
| 诊断 | runtime.diagnostics() |
节点本地不可变快照，不是全局一致视图 |
| 就绪 | runtime.isReady() |
只有 RUNNING 为 true |
| 关闭 | runtime.close() |
释放本地资源，不回滚业务副作用 |
集合公共身份
CollectionLocator = tenantId / applicationId / collectionId
CollectionSpec = locator + schemaId/fingerprint + codec + consistency tier同名 entryKey 只有在相同通信域与 locator
内才属于同一逻辑集合。schema 不兼容应拒绝，而不是尝试猜测解码。
Register
| 操作 | 含义 | 不保证 |
|---|---|---|
put(entity) |
本地提交当前候选值 | 返回时远端已可见 |
get(key) |
当前节点可见值 | 线性化全局读取 |
remove(key) |
本地提交删除 | 所有 peer 同步删除完成 |
all() / size() |
本地 projection 查询 | 全局精确快照 |
changes(options) |
有界观察流 | 不丢事件的历史日志 |
冲突 resolver 需要确定；若依赖输入顺序，应明确拒绝或证明交换律。
Lease
| 操作 | 关注结果 |
|---|---|
acquire |
granted、uncertain、holder、expiry、fencing
token、reason |
renew |
token/holder 仍有效，成员与模式允许 |
transfer |
新 owner 与更高 fencing token |
release |
释放本地协调状态，不撤销已发生外部写入 |
外部资源需要校验 fencing token。AUTONOMOUS 分区模式可能出现临时双 holder；QUORUM 模式在成员不稳定或 quorum 不足时应 fail closed。
CRDT
| 动作 | 含义 |
|---|---|
apply(update) |
把本地 update 合入 state 并生成可传播 delta |
state() |
当前节点的合并状态 |
merger 应满足交换、结合和幂等。PN-Counter 适合可合并运行计数，不自动成为账务事实。
常用构建器
CollectionSpecBuilder.register(...)LeaseCollectionSpecBuilder.lease(...)CrdtCollectionSpecBuilder.crdt(...)
先设置稳定 locator 和 schemaId，再提供 typed codec；spec
由集中装配边界统一构建，避免散落在业务服务中。