发布注记

• 1: SOW v0.4.0
• 2: SOW v0.3.0
• 3: SOW v0.2.0

1 - SOW v0.4.0

SOW 0.4.0 是一次面向 Managed 仓库的完整性与恢复版本：它明确了深度校验的 I/O 契约， 禁止跨无关密钥拼装 RPM 信任，提供可审计的发布目标可变配置修正路径，并补齐 v0.3 迁移与 发布中断恢复的剩余缺口。

Plain 仓库行为与公共 pool/ + dists/ 布局均未改变。

从 0.3 升级

cp -a /srv/sow /srv/sow.backup-before-0.4.0
sow repo migrate pigsty -C /srv/sow
sow repo migrate pgsql -C /srv/sow
sow check -r pigsty -C /srv/sow
sow check -r pgsql -C /srv/sow

Schema v11 修复了 v0.3 的 Dist 生命周期缺陷：过去一个 Dist 变化时，另一个仍 dirty 的 Dist 可能被遗漏，导致 Repository 错误显示为 clean；现在 Repository 状态始终在修改 Dist 的同一事务 中派生。迁移也会修复发布与签名者证据，但不会猜测 v0.3 未记录的历史签名身份：这类身份保持 显式未验证，不能变成 retained trust assertion。

Schema v12 回填只追加的发布目标绑定账本。首次绑定、迁移回填与之后每次操作者确认的 rebind 都会形成彼此独立、不可变的 revision。

每个物理包体只做一次真实性认证

每次 sow check 都会对每个唯一物理包体执行恰好一次权威内容哈希，即使缓存指纹仍然匹配也 不会跳过。证据绑定设备号、inode、size、mtime、ctime，以及真正被读取的文件描述符。同一物理 对象的硬链接可以共享证明；路径替换或并发身份变化会让证据失效并失败关闭。

验证 retained Generation、遍历最终 Manifest 与生成 sow changes 时复用同一份已认证证据。 因此增加 retained Generation 或 Dist 不会放大包体哈希次数。DEB 与无签名 RPM 只需一遍完整 包体流；带签名 RPM 最多再增加一遍从主 Header 到 EOF 的签名流，且与 Dist 或信任环数量无关。

软件包事实也只按本次选中的摘要集合，以有界、确定性的 SQLite 批次读取。64 MiB 包体的暖构建 不读取包体；指纹漂移与 facts 缺失共享同一次权威包体读取，不再分别扫描。

独立 RPM 信任环

RPM 嵌入签名会在每个候选 trust ring 内独立验证：所有可识别签名 packet 必须在同一个 ring 中 通过，且至少一条通过的路径必须认证 payload。这样既保留历史 CentOS v3/v4 签名与有意双签包的 支持，又禁止把不同 ring 的 packet×key 成功项拼成虚假的单 key retained 信任结论。

当前策略 ring、每个 retained 单 key ring 与组合 trusted ring 共用同一遍签名流。增加密钥只会 改变授权结论，不会增加读取包体的次数。

安全重绑定目标与公共验证

sow publish TARGET --rebind 是显式、由操作者确认的修正路径：它允许修正目标的可变配置， 同时保留原存储身份与恢复状态。

普通 publish 遇到不一致时会明确提示 --rebind，绝不会静默接受新值。Rebind 与 publish 使用同一 组独占锁，追加一条审计 revision，并可继续前滚处于 commit-intent 的 active attempt。目标维护 未完成时禁止改变 TTL；filesystem 正在进行 conditional-delete 维护时禁止改变公共端点。历史 grace deadline 永远不会被缩短。

Filesystem 与 R2 的 HTTP(S) 公共端点现在共用同一套强化 verifier。响应 Header 与 Body 空闲进度 分别设定 Deadline，因此大对象只要持续前进，即使总传输超过两分钟也可完成。普通 canonical GET 始终是最终权威；no-cache 请求只用于促进 revalidation。陈旧内容与 404 按 max_cache_ttl 等待， 408/425/429/5xx 使用较短的有界重试窗口，超长响应失败关闭。Filesystem 公共缺失必须最终由 canonical 404/410 证明。R2 远端删除仍明确禁用，Target GC 只报告候选。

Filesystem 目标还会在持久绑定之前按 prospective physical path 检查别名，包括大小写不敏感 卷上的大小写别名。预检失败不会留下 binding row，也不会创建目标 prefix。

恢复、CLI 与实现收敛

• 增量发布恢复只接受每个指针的精确旧 Checkpoint 或目标 Generation 字节；未知或第三种身份 仍然失败关闭。
• 日常发布只验证精确 Changed Object Set，不再下载完整 Public Generation。No-op 与 Applied-checkpoint Recovery 复用完整私有 Inventory Evidence；Target GC 只扫描所需协议 Pointer。
• R2 操作采用分阶段 Header/Idle Deadline、有界条件式 Multipart Upload、可重试读写，并在 Complete Multipart 前核对整对象 SHA-256。
• Generation signer row 成为覆盖局部构建、Dist 增删、迁移、Retention 与本地 GC 的精确 Manifest side table。
• 默认重复执行 sow add 时，即使 Package Object 已复用，也会收敛先前 --skip 或配置变更 留下的选中 dirty Dist。
• sow rm --check 与写操作共享配置门禁，返回精确、完全不写入的预览；结果不再依赖 scratch 文件系统是否同设备。
• 所有 Managed 命令现在都有面向人的输出；--json 继续提供稳定 sow.cli/v1 Envelope，并在 失败时保留已提交的部分结果及诊断性的 check/preview 结果。
• 退役的 APT v1 Builder、External Sort、Empty-Dist 实现与 Git-tracked by-hash ledger 已移除； 当前 Plain/Managed APT 解析与渲染路径仍有覆盖。

验证与制品

Release 门禁覆盖完整 Go 测试、vet、staticcheck、dead-code reachability、漏洞与 RPM Fork Provenance 检查、Race Test、Linux amd64/arm64 构建，以及上述确定性包体/facts I/O 契约。 Release 二进制使用 Go 1.27.0 从 v0.4.0 源码 Tag 构建。从源码构建现在要求 Go 1.27.0 或更新 版本（0.3 为 1.26.5）；AWS SDK、SQLite、压缩与加密依赖同步刷新，质量门禁固定 staticcheck v0.8.1、deadcode v0.49.0 与 govulncheck v1.7.0。

本次制品包含四个 Linux/macOS 归档、两个 RPM、两个 DEB 与 SHA256SUMS。每个归档包含 sow、README.md、CHANGELOG.md 与 LICENSE；Linux 原生包随二进制安装 Apache-2.0 许可证。

获取发布版本

通过下载页面获取平台对应命令与已验证摘要，或查看 GitHub Release。安装后先运行 sow version， 逐个迁移 v0.3 Repository，再以 sow check 作为发布前门禁。

长期维护的契约见 Managed 工作区、 签名模型与发布与恢复。

2 - SOW v0.3.0

SOW 0.3.0 围绕性能、持久性与产品边界完成了一次集中改进：Plain 仓库生成只需一遍包体处理； Managed 仓库消除了逐对象成员查询，复用经过认证的软件包事实，并用有界组提交提升载荷。正式 交付的二进制与发布流水线也统一收敛到 SOW 实际支持的仓库工作流。

Plain：一遍完成包体处理

默认无签名 sow create 路径通过 --jobs 控制并行度，每个 RPM 或 DEB 只做一次哈希与解析， 随后直接利用保留的检查结果渲染元数据。发布前只做最后一次软件包集合与文件 stat 快照检查， 无需再次读取和哈希所有包体，也能拒绝并发输入变更。

Plain 元数据是可以重建的派生状态。实现不会创建操作日志、恢复垃圾区、回滚前镜像，也不会 重复计算包体哈希。进程中断后重新运行 sow create，即可从软件包目录重建元数据。

Pigsty 预处理会保留 RPM Header 中架构为 i386、i486、i586 或 i686 的软件包， 让它们继续进入仓库元数据与 repo_complete 校验清单；DEB i386 与精确匹配 Patroni 3.0.4 的过滤规则仍按预期生效。

Managed：扩展规模，不放松完整性

成员关系表增加了按包体 SHA-256 的反向索引，Desired 与 Built Membership 通过一次有序批量 投影展开，不再为每个对象单独查询。项目基准中，包含 5,000 个对象的 Dist 列表从约 4.1 秒 缩短至 33 毫秒；50,000 个对象从超过十分钟仍未完成，缩短到约 300 毫秒。

以不可变包体 SHA-256 为键的软件包事实缓存可以随时重建。Ingest 对每个新 RPM 或 DEB 完整 认证并解析一次，保留渲染元数据所需、与具体视图无关的事实。构建时批量载入这些事实并在内存中 匹配；记录缺失或损坏时，再从经过认证的包体惰性重建。

对于未改变的 Pool，暖构建使用设备号、inode、size、mtime 与 ctime 指纹校验载荷，包体读取量 降为零。指纹漂移时执行一次权威 SHA-256 校验并修复缓存路径；sow check 仍负责显式的完整 密码学审计。RPM 元数据产物与 DEB 架构索引使用有界 --jobs 并发，Generation Manifest 与 Changeset 行批量写入，最终规范化复用已有描述符快照，不再重新扫描 Pool。

有界提交与可观察构建

Managed 载荷提升采用有界的单写入者组提交。每批最多处理 512 个对象或 1 GiB：先创建公开 Pool 链接并持久化各目标目录，再移除 pending 名称并持久化共享的 pending 目录。崩溃因此只会留下 可恢复的“仅 pending”“精确双链接”或“仅 Pool”状态；两个名称同时持久丢失仍是完整性错误。

Pending 载荷在私有 0700 目录中直接使用最终的 0644 权限，因此提升只涉及命名空间变更。 Pending 源保护记录对象身份，不会在整个构建期间为每个软件包持有一个描述符，描述符占用保持 有界。发布载荷时也会先持久化目标目录项，再解除源名称。

长时间构建会为渲染、载荷提升、Dist 发布、规范化与收尾阶段追加结构化 build_progress 事件。它们可在 sow log 中观察，但不会为每个阶段增加数据库 checkpoint， 因此进度记录不会让本可成功的构建失败。

收敛发布与运行时边界

R2 发布传输只保留 SOW 实际使用的存储原语：list、head、get 与 conditional put。远端 GC 保持只报告、不删除对象的边界。未使用的云控制、CDN、Edge Worker、迁移程序与替代运行时路径 已从活动代码树移除，正式 CLI 只依赖统一的仓库核心；默认 go test ./... 因而覆盖完整的活动 实现。

正确性与发布质量

• 本地 GC 可以安全移除 Generation 中记录的唯一大小写折叠 Pool 别名，这对大小写不敏感的 文件系统尤其重要。路径、大小与摘要仍必须标识同一不可变对象；存在歧义或漂移时拒绝执行。
• 每个归档都包含 LICENSE。RPM 与 DEB 声明 Apache-2.0，并分别把许可证安装到 /usr/share/licenses/sow/LICENSE 与 /usr/share/doc/sow/copyright。
• CI 强制执行格式化、模块整洁、vet、静态分析、死代码检查、性能测试编译、完整测试、竞态 测试、干净交付检查与软件包快照检查。
• 集成门禁覆盖正式二进制的干净环境混合 RPM/DEB 流程、Ubuntu 22.04 上无签名 Plain APT 的 精确安装、AlmaLinux 8/9/10 的 DNF 签名切换探针，以及固定 MinIO 环境中的 S3 条件写操作。
• 正式发布包含 macOS 与 Linux 的 amd64/arm64 归档、两个 Linux 架构的 RPM 与 DEB，以及 SHA256SUMS。

获取发布版本

通过下载页面获取对应平台的安装命令，或在 GitHub Release 查看全部交付物。安装后运行 sow version，确认使用的是选定的二进制。

完整操作契约见 Plain 模式、Managed 模式 与平台与集成。

3 - SOW v0.2.0

SOW 0.2.0 是 Pigsty 出品的自包含 RPM/DEB 仓库管理器，Release 资产以单个 Go 可执行文件覆盖 Linux 与 macOS 构建目标。

两种工作模式

Plain 模式 给目录顶层已有的 RPM 与 DEB 文件就地生成索引：

sow create /srv/repo

它写入 repodata/、Packages 与 Packages.gz。Plain 模式没有 Workspace、状态数据库、 Generation，也不生成或签署 DEB Release。

Managed 模式 负责包成员关系与完整生命周期：

mkdir -p /srv/sow && cd /srv/sow
sow init .
sow repo new pigsty
sow dist new el9 --format rpm -r pigsty
sow add /path/to/packages/*.rpm -r pigsty -d el9
sow check -r pigsty

每个接纳的包体只在 pool/ 下保存一次；RPM 与 APT 客户端视图位于 dists/，并以不可变 Generation 落成。

生命周期控制

Managed 仓库提供：

• 严格的 sow/v3 配置与显式成员策略；
• RPM 元数据、APT 元数据与可选 RPM 包体签名；
• 低成本 status 与作为发布门禁的九层 check；
• 可恢复的 filesystem 与 R2 发布尝试；
• 显式保留 Generation 与基于可达性的本地 GC；
• 面向拒绝 rpm-md 父级相对路径的消费者的独立 rpm-leaf 导出。

规范 Managed 树必须作为完整仓库交付。已配置目标使用 sow publish；其他传输方式应先把 整根复制到离线 staging，再原子切换。不要逐文件更新在线仓库。

兼容性证据

当前测试套件证明：两种格式都能由现行 CLI 在干净环境构建；Ubuntu 22.04 能消费 Plain APT 仓库；AlmaLinux 8/9/10 探针覆盖 RPM 分离签名行为；另有独立 S3 兼容 Provider Fixture。 这些探针本身不能证明完整的现行 Managed DNF/APT 或 R2 CLI 端到端验收。

确切声明边界见兼容性，全新安装入口见 快速上手。