设计 on SOW

设计原则

Mon, 01 Jan 0001 00:00:00 +0000

SOW 首先不是一个“元数据生成器”，而是一个所有权与状态迁移系统，只是它的输出恰好是 APT 与 RPM 仓库。下面这些原则让整套系统保持可推理。

每个持久事实只有一个主人

每类持久事实都只有一个作用域与权威：

系统模型

Mon, 01 Jan 0001 00:00:00 +0000

SOW 刻意把模型分层：配置表达意图，数据库记录有主状态，公共树是确定性投影。任何一层都不能悄悄替代另一层。

对象层级

Workspace
├── Repository
│ ├── Package Object
│ ├── Dist
│ │ └── Membership -> Package Object
│ ├── Desired 状态
│ ├── Built Generation
│ └── Retained Generation 引用
└── Publication Target
 └── Repository + provider + prefix

Workspace

Workspace 提供发现、配置与协调，拥有 sow.yml、私有 .sow/ 目录和稳定锁路径；它不是包体去重域。

单包体仓库

Mon, 01 Jan 0001 00:00:00 +0000

0.3 开发线调整了 RPM 物理布局，但保留 v0.2 确立的所有权模型。它的目标很精确：在一个 Repository 及其每个发布前缀内，每个 live Package Object 恰好只有一条包体路径。

开发线设计

本页描述已经落入 0.3 源码的布局；已发布 v0.2 的操作参考仍然使用 C2 view-local 硬链接。迁移现有 v0.2 仓库前，请先读设计演进。

发布与恢复

Mon, 01 Jan 0001 00:00:00 +0000

构建与发布是两个独立状态迁移。构建产生与 target 无关的 Generation；发布把该 Generation 应用到一个供应商前缀，并记录足以在不猜测的前提下恢复的证据。

所有权拆分

Repository 作用域	Target prefix 作用域
Package Object	Publication Attempt
Desired 与 Built 状态	Applied Checkpoint
Generation 与 Changeset	远端 inventory
retained 包体/元数据引用	grace 与删除证据

这项拆分避免把 filesystem 发布成功当成 R2 的证据，也避免一个 target 的半完成尝试污染另一个。

兼容性边界

Mon, 01 Jan 0001 00:00:00 +0000

“兼容”太宽泛，不足以成为工程结论。一个包可能安装成功，但镜像工具拒绝同一份元数据；一棵树可能在 POSIX 磁盘上去重，上传后却变成多个完整对象。因此 SOW 把兼容性拆成独立门禁。

设计演进

Mon, 01 Jan 0001 00:00:00 +0000

SOW 的旧文档来自三套实质不同的系统。缺少版本边界时，互相矛盾的结论看起来像同时成立。本页保留有价值的决策，同时明确它们各自的作用域。

时间线

版本线	主要问题	物理模型	处置
V1 实验（2026-07）	纳管 Pigsty 既有 APT/YUM 树与远端发布流程	Git/CAS、route-aware 投影、edge/provider 契约	归档为研究与实现证据
v0.2.0	交付紧凑的本地 Plain + Managed 仓库管理器	根 Pool + C2 view-local RPM 硬链接	已发布；操作文档继续在线
0.3 开发线	每个 Repository/target prefix 只发布一份正典包体	根 Pool + 纯元数据 view + target-scoped 发布	源码已实现；发布证据待完成

V1 留下了什么

V1 大范围探索了既有仓库纳管、远端发布、供应商 fencing、边缘鉴权、迁移、恢复与大仓库证据。它具体的 Git/CAS/route 模型大多已被替换，但几条原则保留下来：