结构族与事务契约(Structures / Transactions / Common)
索引最小协议(IIndex / IKeyResolver)
IIndex<in TKey>(TKey : notnull)——装配点最小公共协议:Find(点查→地址,Empty=不存在)/Insert/Delete/Count/ByteSize。两族不设公共基类:有序遍历/range 选比较族 (BTree/SkipList)、极省内存点查选探测族(Hash)——选族即选消费形态。IKeyResolver<TKey>——按地址读 key + 按范围扫 key 流(两族恢复自建的流源): 无 value(索引不消费 value,交付是组合层点查最后一跳)、无 header(有效性过滤内化在 ScanAsync)、无写入(写编排归组合层:先 ring.Write 得地址再 index.Insert)、无批量随机读。RingBase<TKey>直接实现,无适配层。
扫描游标(IRecordScanCursor / IStructureScanCursor)
跨结构统一游标保证口径(静态集无重无漏/快照游标语义/游标易失锚)—— 见 scan-cursors.md。
Transfer 族(状态导出/导入——raft SM 快照底座)
ITransferWriter/ITransferReader + 异步形态 IAsyncTransfer* + ICommonReaderWriter——
三段式状态传输(Export → 传输通道 → Import)的契约面;各产品 SM 适配按 D7 三段式补齐
(决策表/暂存覆盖层+世代与水位 max 合并)。
事务参与面(ITransactionLog / ITransactionParticipant / IEpochProtected)
ITransactionParticipant——跨结构 2PC 参与者:Prepare(seq)(落盘悬空)/ConfirmCommitted(seq)(推进提交水位)/Abort(seq)(回退到上一提交边界)/OnCommitted(seq, callback)(提交回调)。Ring/Log 同构实现(RingBase.Transaction / LogBase.Transaction 范式)。- 窗口契约:上一提交点之后的全部写入必须都属于被回滚事务(标准 2PC WAL 契约)。
- meta Disabled 下 Prepare/Confirm 照常可调但恢复裁决不可用——meta 落盘的 LastPreparedSeq/CommittedTailAddress 是跨崩溃裁决唯一依据(见 meta 契约)。
ITransactionLog(决策日志面)/IEpochProtected(epoch 保护标记——保护区内 Advance 禁令)。
异步操作与序列化(Common / Serialization)
IAsyncOperation/AsyncOperationStatus(Contracts.Common)——带进度/结果句柄的长操作 统一面(bridge/备份导出等消费)。ISpanSerializer——Span 面序列化最小契约。
反模式
- 给 IIndex 加 value 读取或写入方法——职责归组合层(Ring 真源 + 组合编排)。
- 参与者 Prepare 后不 Confirm/Abort 任选其一遗漏——悬干窗口跨崩溃由 meta 裁决, 无 meta 即静默失效(先配底座再接 2PC)。
- 结构层裸写 IRecovery 绕过骨架——生命周期骨架=信任边界(判例在案)。
源码:Structures/、Transactions/、Common/、Serialization/。