版本控制后端【免费下载链接】loreLore is a next-generation, open source version control system项目地址https://gitcode.com/gh_mirrors/lore6/lore点击查看免费下载本文基于 Lore 项目的决策记录 00002-branch-tracking-in-mutable-store.md解析 Lore 如何把分支最新指针branch latest pointer、分支配置和分支列表从每分支一个独立文件迁移到 mutable store / immutable store 统一存储中。读完后你将理解这一架构决策的动机、备选方案对比、代价权衡并能在仓库源码中找到该决策的完整落地证据——包括键值派生方式、compare-and-swap 指针更新以及 typed items 存储升级路径。背景与问题陈述该 ADR状态accepted日期2024-03-10决策人Mattias Jansson、Paul Sharpe、Joshua Cohen咨询方Manuel Lang、Wouter Burgers开篇指出 Lore 当时的分支存储方式存在结构性问题现状Lore 此前将分支信息branch information与当前最新指针current latest pointer作为每个分支一个独立文件存放在客户端问题一无法向服务端平滑迁移。这套按分支散落的文件布局难以翻译成多种后端backends的实现也不符合客户端与服务端通过同一个共享核心库复用同一份代码的设计目标问题二序列化数据散布在多个位置。同一份逻辑数据被拆分到多个独立文件使得备份backup和数据迁移data relocation都必须逐个感知并处理这些文件任何遗漏都可能导致数据丢失。原文对两个备选方案与最终结论的完整陈述见 ADR 原文。决策驱动因素ADR 明确了本决策要满足的两条核心驱动因素易用性在库library内部以及对外部协议external protocols暴露时都要易于使用存储收敛将数据收敛到尽可能少的独立系统与序列化路径中即能用现有 store 解决就不新增一套存储。这两条驱动因素贯穿了后文对两个方案的评估。备选方案一继续使用当前的独立文件按 ADR 的描述该方案的具体形态是分支最新指针branch latest pointer与分支名写入.lore目录中的一个 tracking 文件服务端必须复用同一套或自行实现一套tracking 序列化格式任何数据备份或传输操作都必须显式知晓这些文件的存在并在每次操作中把它们包含进来需要专门的 API 命令来 get/set 最新指针与分支配置分支列表要么被收集为一组 tracking 文件要么额外维护一个独立的列表文件。从结构上看这个方案的主要风险点在于分支数据与通用数据形成两条平行的存储路径备份工具、传输协议、服务端实现都必须分别处理两条路径复杂度随功能增长线性扩散。备选方案二使用 Mutable StoreADR 中该方案的完整设计是分支最新指针存入 mutable store键的输入为仓库 ID 分支名共同参与哈希分支配置存入 immutable store并在 mutable store 中维护一个指向它的可变指针键的输入同样是仓库 ID 分支名分支列表同样存入 immutable store用 mutable store 中以仓库 ID为哈希键的指针引用由于数据可以直接从 mutable store API 读取不需要新增任何 API 命令ADR 也保留了为了可读性可以再引入专用 API的余地数据备份与传输无需额外考虑——所有分支数据都位于通用数据存储之内。immutable store 存值 mutable store 存指针正是 Lore 存储体系对大对象与小引用分离处理的典型模式不可变的分支配置内容一旦写入 immutable store 便永不变化mutable store 只保留随时可改的指针与状态量。决策结果最终采纳Mutable Store 方案。ADR 给出的核心理由是减少独立序列化方式的数量与存储位置统一客户端与服务端的数据存储对网络的访问层可以独立设计——既可以是对 mutable store 的裸读取raw read走通用 mutable store API也可以为每个使用场景提供专用 API。这一设计把存储层如何组织与协议层如何暴露解耦了决策只约束前者后者保持开放。后果ConsequencesADR 如实记录了该决策的正负两面正面所需的具体序列化代码更少——一切数据都进入既有的 mutable / immutable store不需要为分支再发明文件格式负面数据被混淆obfuscate了。分支指针不再是可以直接cat出来的人类可读文件做取证分析forensics时无法通过 dump 文件内容直接看出某个分支必须借助工具经哈希键反查。确认ConfirmationADR 记录曾编写过一个测试实现test implementation以证明该方案可行。该实现移除了对每仓库独立存储的最后残留需求使仓库repository现在可以过渡为仅一个不透明标识符opaque identifier而不再是序列化在磁盘多个位置的复杂数据结构。这一点在后续源码中可以得到印证见下文仓库已过渡为不透明标识符。源码佐证分支键值如何派生ADR 中以仓库 ID 和分支名作为哈希键输入的描述在 lore-revision/src/branch.rs 中有精确实现。关键常量与派生函数为pub const LATEST: str branch-head; pub const LATEST_STATUS: str branch-head-status; pub const LATEST_HISTORY: str branch-head-history; pub const LAST_SYNC: str branch-last-sync; pub const METADATA: str branch-metadata;函数mutable_key将 salt、function 名如branch-head、仓库 IDhex 编码与分支 IDhex 编码一起送入hash::hash_function_args派生出存储键同时映射出KeyTypepub fn mutable_key( salt: [u8], function: str, repository: RepositoryId, branch: BranchId, ) - (Hash, KeyType) { let key hash::hash_function_args( salt, function, hex::encode(repository.data()).as_str(), hex::encode(branch.data()).as_str(), ); let key_type mutable_key_type(function); (key, key_type) }其中mutable_key_type将逻辑函数名映射为强类型的键类型branch-metadata映射到KeyType::BranchMetadataid映射到KeyType::BranchIdbranch-head映射到KeyType::BranchLatestPointer其余落为KeyType::Untyped。KeyType枚举定义于 lore-base/src/types/store_types.rs这意味着 mutable store 的每个条目都带有一个类型标签——这正是typed items存储升级见下文能按类型批量迁移的前提。此外还有mutable_name_key以分支名小写化派生 name→id 映射键以及store_name_to_id/load_name_to_id等函数分支名到分支 ID 的映射同样存放在 mutable store 中本地未命中时可回落到远端branch_query并回填缓存。可见 ADR 所述分支名/ID 信息与最新指针被统一收纳进同一套键值体系。源码佐证compare-and-swap 的指针推进最新指针是并发敏感的状态量。在 lore-revision/src/branch.rs 中store_latest以 compare-and-swap 语义推进指针pub async fn store_latest( repository: ArcRepositoryContext, branch: BranchId, previous: Hash, latest: Hash, status: BranchLatestStatus, ) - Result(), BranchError { let stored mutable_try_store(repository.clone(), LATEST, branch, previous, latest).await?; if stored ! previous { // ... return Err(BranchAdvanced.into()); } // Server does not store latest status or history if execution_context().is_server() { return Ok(()); } // ... 客户端额外写入 LATEST_STATUS 与 latest history }其底层mutable_try_store调用 mutable store handle 的compare_and_swap(repository.id, key, expect, value, key_type)。这体现了 ADR 决策结果中客户端/服务端复用同一套 store 代码的意图同一函数在两种执行上下文中分支处理——服务端只更新指针本身客户端额外维护LATEST_STATUSdivergent/convergent 状态与 latest history。与immutable store 存值 mutable 指针模式直接对应的是BranchLatestHistory#[derive(Clone, Debug, Default, IntoBytes, FromBytes, Immutable)] pub struct BranchLatestHistory { pub revision: Hash, pub previous: Hash, }该结构带Immutable派生内容写入 immutable storemutable store 中只存一个哈希指针LATEST_HISTORY键。读取侧load_latest_history通过BranchLatestHistory::read_from_immutable(...)用指针换回内容而 lore-revision/src/branch/latest.rs 中的list函数则沿previous链向前翻页默认 30 条DEFAULT_LATEST_LIST_LIMIT逐条发出LoreBranchLatestListEntry事件——这就是lore latest list类命令的底层数据流。分支列表与仓库的不透明标识符化ADR 确认部分提到仓库现在可以仅作为不透明标识符。在源码中仓库上下文RepositoryContext持有仓库 ID 与 salt分支数据的存取全部经由repository.id 派生键完成仓库目录本身不再承载分支元数据的结构化文件。分支名→ID 映射、分支配置指针、最新指针、last-sync、历史链指针全部汇入 mutable store而 lore-revision/src/store/mutable.rs 中的MutableStore类型直接复用lore-storage的LocalMutableStorepub(crate) type MutableStore lore_storage::local::mutable_store::LocalMutableStore;与 lore-storage/src/local/mutable_store.rs 及一致性套件 lore-storage/src/mutable_conformance.rs 共享同一套本地实现——后者包含对KeyType::BranchMetadata/KeyType::BranchLatestPointer条目的读写覆盖说明分支追踪数据已被当作 mutable store 的常规负载进行一致性验证。决策的后续演进从 Untyped 到 Typed Items值得注意的是当前仓库中的 mutable store 已经不是 ADR 最初描述的裸哈希键值表而是经历了typed items 升级。lore-revision/src/store/mutable.rs 中的upgrade流程会在store.needs_upgrade()时调用migrate_initial_to_typed反序列化所有 bucket对每个条目尝试从 immutable store 或远端加载其值根据值的大小判定数据类型并为其打上KeyType标签随后写入version文件值为MutableStoreVersion::TypedItems。这可以推断出ADR 中分支指针以仓库 ID 分支名为哈希输入的裸键initial 格式如今在升级路径中被归类并升级为带类型标签的条目如BranchLatestPointer既保留了原决策的键布局又为按类型枚举、校验和维护打下了基础。该决策还为后续 ADR 铺了路00014-anchor-tracking-in-mutable-store.md 明确将与 ADR 00002 保持一致的存储收敛列为决策驱动因素并把 clone 的 checkout 锚点anchor也纳入 mutable store键由 per-clone 实例 ID 派生使分支指针、同步状态、锚点这类可变状态在单次 flush 中原子落盘。可以说ADR-00002 确立的可变状态一律进 mutable store原则后来扩展为 Lore 可变状态管理的整体范式。权衡总结与验证路径维度独立文件方案Mutable Store 方案采纳序列化方式数量分支 tracking 文件 通用 store两套一套复用既有 mutable / immutable store客户端/服务端代码复用服务端需独立或复刻 tracking 序列化同一共享核心库、同一 store API备份/迁移必须显式包含 tracking 文件无额外考虑随通用数据走专用 API需要 get/set 指针的专门命令不需要可选为可读性补充人类可读性/取证直接读文件即可需经哈希键与工具反查若要在本仓库中复核本决策的落地情况建议沿以下路径阅读决策原文与后续演进00002-branch-tracking-in-mutable-store.md、00014-anchor-tracking-in-mutable-store.md分支键派生与指针读写lore-revision/src/branch.rsmutable_key、mutable_try_store、store_latest、load_latest、store_name_to_id最新历史链的 immutable 存储与列表输出lore-revision/src/branch/latest.rs本地 mutable store 实现与类型标签lore-storage/src/local/mutable_store.rs、lore-base/src/types/store_types.rs初始格式到 typed items 的升级迁移lore-revision/src/store/mutable.rsupgrade/migrate_initial_to_typed。综合来看ADR-00002 是一次典型的用少量可读性换取存储架构统一的决策它以牺牲dump 文件看分支的便捷性为代价换来了序列化路径收敛、客户端/服务端同构、备份迁移零特例以及为后续锚点追踪ADR-00014等可变状态管理留下的扩展空间。赞分享版本控制后端【免费下载链接】loreLore is a next-generation, open source version control system项目地址https://gitcode.com/gh_mirrors/lore6/lore点击查看免费下载相关推荐终极指南Hyperswitch分布式追踪如何保障支付请求链路的稳定性与可观测性终极指南Hyperswitch分布式追踪如何保障支付请求链路的稳定性与可观测性 Hyperswitch作为一款高性能的支付网关和微服务框架其分布式追踪能力是后端金融科技Semantic Kernel 架构决策实录为何 Entity Framework 不被采纳为 Vector Store 连接器ADR 0051 深度解析Semantic Kernel 架构决策实录为何 Entity Framework 不被采纳为 Vector Store 连接器ADR 0051 深度解析人工智能大模型AI AgentAgent 框架多智能体RAG如何使用Firebase会话分析实现iOS应用用户行为追踪完整指南如何使用Firebase会话分析实现iOS应用用户行为追踪完整指南 Firebase iOS SDK是苹果应用开发的强大工具集其中会话分析功能能够帮助开发者移动开发后端认证鉴权上一篇Introduction to Bash Scripting 系列精讲Bash 循环for / while / until / break / continue完全指南下一篇强力指南如何用AB下载管理器解决大文件下载速度慢的烦恼创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
