存储地址与引擎契约(Storage/)
LogicalAddress(16B 逻辑地址)
readonly struct:[SegId 4B][Extension 4B(ABA 防护)][Offset 8B]——地址即身份:
判等/哈希/排序只比较地址本身,不回源数据。
- 双哨兵语义(最高频误用点):
Empty= (0,0,0)——seg0 的起点,是合法地址,不是"没有值";Invalid= (-1,-1,-1)——**"无值/未初始化/越界"**哨兵;- 判空一律
IsValid(SegId >= 0 && Offset >= 0)——addr != Empty是错误写法 (把合法起点当成了无值)。新 API 的无值表示必须用 Invalid 并先核对既有哨兵约定。
- 段表算术教义:地址推进/回退/跨段一律走
AdvanceAddress/RetreatAddress/GetDistance段表算术——禁手工拆字段 ±(Hollow 占位连续;三禁:只推不减=死循环、break=跨 Hollow 提前停、替换须核对循环分支语义)。 - 边界规范形:exact-fill 停驻
(segId, GrowthLimit)——(seg+1, 0)哨兵形态已废除; 区间写法半开[start, end)。 - 排序 = 段主序(SegId 优先,Offset 次之)——与 SortedDictionary 键元组序同构;
C# ValueTuple 无
</>=(CS0019),用领域比较运算符直比。
IStorageEngine(引擎契约)
继承 IStorageInfo(纯信息视图:定位/配置/路径解析)+ ILifecycle<EngineRecoveryHints>
(观测:IsReady/RecoveryState/WaitForReady*)——子系统只依赖 IStorageInfo,不与 IO 耦合。
- 启动不在接口面:
Initialize已消除——启动统一经StorageEngineBuilder.Start/StartAsync一步到位;恢复 hints 经Start(hints)传入,段生长上限/分段开关是构造期配置。 - IO 面:
AppendAsync(顺序追加,返回起始逻辑地址)/WriteAsync(原地覆写)/ReadAsync/Flush(同步三重载:全量/至 upTo/Range)/Truncate/ 回收压缩族(StartReclaim/StartCompact/StartRangeCompact)。 - 动态水位:
AllocatedTail(分配尾,含攒批窗口)与提交尾分离——分配尾 ≠ 可见尾。
恢复与枚举
EngineRecoveryHints(committedTailHint, allocatedTailHint)——只携带双尾修正 (可空 = 不修正);生命周期参数(段生长上限/分段开关)构造期传入,不经此类型。 构造 = 配置,启动 = 双尾。RecoveryState/RecoveryPhase/RecoveryProgress见生命周期契约。ReadDirection(Forward/Backward 顺序读向)、ISequentialReader(顺序读游标—— 推进不减 remaining 的"防御推进"禁令见 log.md)、SnapshotMode(流式/段式快照形态)、CompactResult/CompactStatus(回收终态:Committed+sparse / Committed / Wasted / Aborted ——ReclaimRollback→MarkAbort 语义勿改回)。MagicLocation:Magic 粗定位(恢复扫盘 MagicLocator 的契约形态)。
反模式
- 用 Empty 表示"无值"——把 seg0 合法起点当哨兵;无值用
Invalid+IsValid判定。 - 手工拆 SegId/Offset 做地址算术——跨段/Hollow 场景必错;统一走段表算术 API。
- 子系统依赖 IStorageEngine 拿信息——只该依赖
IStorageInfo(避免与 IO 耦合)。 - EngineRecoveryHints 塞生命周期配置——构造期参数混进启动修正,配置/启动两轴混淆。
源码:Storage/(LogicalAddress / IStorageEngine / IStorageInfo / EngineRecoveryHints /
ReadDirection / ISequentialReader / SnapshotMode / CompactResult / CompactStatus / MagicLocation)。