From 8cb2954aa99fbc6a48763c56d8a1d28f1bf6fb5c Mon Sep 17 00:00:00 2001 From: Sunrisepeak Date: Sat, 17 Oct 2026 11:11:58 +0900 Subject: [PATCH] feat(loader): a version entry's floor -- the oldest installed revision still usable (0.0.65) `floor = N` on a version entry (0 <= N <= revision) is parsed into `PlatformResource::floor`, and `resolve_resource` reports the floor of the entry an alias resolves to. Absent is 0; a floor above the revision reads as the revision. Why: a raised `revision` used to mean "every installed payload of this version is stale", so a client replaced llvm, gcc and glibc on a user's next build for revisions that only removed hard links for Android or regenerated a cfg. Only the recipe's author knows whether a revision fixes something every installed payload has; `floor` lets the author say so, and a client keeps a payload at or above it (mcpp design 2026-10-17, L1). Tests: LoaderTest.V2_Floor_ParsedAndBoundedByRevision. Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com> --- docs/architecture.md | 1 + mcpp.toml | 2 +- src/xpkg-compat.cppm | 3 +++ src/xpkg-loader.cppm | 1 + src/xpkg.cppm | 8 ++++++++ tests/fixtures/pkgindex/pkgs/v/v2revision.lua | 7 +++++++ tests/test_loader.cpp | 19 +++++++++++++++++++ 7 files changed, 40 insertions(+), 1 deletion(-) diff --git a/docs/architecture.md b/docs/architecture.md index 94ffadb..417bbd6 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -77,6 +77,7 @@ graph TD - `load_index_db(path)` / `save_index_db(index, path)` — JSON 格式索引持久化 - 平台继承:平台段的 `inherits = "<平台>"` 与 V1 写法 `{ ref = "<平台>" }` 都表示继承。加载时沿继承链补齐:本平台缺少的版本取自被继承的平台,`deps`、`exports`、`source` 在本平台未声明时同样继承;遇到环或不存在的平台即停止。平台级的 `ref` 不再生成名为 `ref` 的版本(0.0.64) - 版本条目的 `min_client`:能使用该版本的最旧客户端版本,解析为 `PlatformResource::min_client`。未指定版本时,客户端据此跳过自己不能使用的版本(0.0.64) +- 版本条目的 `floor`:该版本仍可用的最旧打包修订号(`0 ≤ floor ≤ revision`,缺省 0),解析为 `PlatformResource::floor`,`resolve_resource` 随 `ref` 报告解析到的条目的值;高于 `revision` 时按 `revision` 读。客户端保留记录修订号不低于它的已装载荷,替换低于它的(0.0.65) ### mcpplibs.xpkg.index — 索引层 diff --git a/mcpp.toml b/mcpp.toml index f37d247..b750984 100644 --- a/mcpp.toml +++ b/mcpp.toml @@ -1,7 +1,7 @@ [package] namespace = "mcpplibs" name = "xpkg" -version = "0.0.64" +version = "0.0.65" description = "C++23 reference implementation of the xpkg V2 spec (multi-arch)" license = "Apache-2.0" repo = "https://github.com/openxlings/libxpkg" diff --git a/src/xpkg-compat.cppm b/src/xpkg-compat.cppm index 2206d5a..6fa9e1e 100644 --- a/src/xpkg-compat.cppm +++ b/src/xpkg-compat.cppm @@ -30,6 +30,8 @@ struct ResolvedResource { // The packaging revision of the entry that supplies the payload: for a // `ref` alias, the revision of the entry the alias resolves to. int revision = 0; + // That entry's `floor`: the oldest installed revision still usable. + int floor = 0; }; std::expected resolve_resource( @@ -118,6 +120,7 @@ std::expected resolve_resource( ResolvedResource result; result.version = resolved_version; result.revision = resource->revision; + result.floor = resource->floor; if (arch_resource != nullptr) { result.url = arch_resource->url; result.sha256 = arch_resource->sha256; diff --git a/src/xpkg-loader.cppm b/src/xpkg-loader.cppm index ca70865..245d1a6 100644 --- a/src/xpkg-loader.cppm +++ b/src/xpkg-loader.cppm @@ -500,6 +500,7 @@ PlatformMatrix parse_xpm(lua::State* L, int pkg_idx) { res.sha256 = get_str(L, res_idx, "sha256"); res.ref = get_str(L, res_idx, "ref"); res.revision = get_nonneg_int(L, res_idx, "revision"); + res.floor = std::min(get_nonneg_int(L, res_idx, "floor"), res.revision); res.min_client = get_str(L, res_idx, "min_client"); // ---- V2 multi-arch shapes ---- diff --git a/src/xpkg.cppm b/src/xpkg.cppm index 3446acb..7cadeb6 100644 --- a/src/xpkg.cppm +++ b/src/xpkg.cppm @@ -52,6 +52,14 @@ struct PlatformResource { // states none. A client records the revision it installed and treats a // different recipe revision as not installed (xpkg V2 spec, "revision"). int revision = 0; + // The oldest packaging revision of this version that is still usable + // (`floor = N`, 0 <= N <= revision): a client keeps an installed payload + // whose recorded revision is at least the floor, and replaces one below + // it. 0 when the entry states none -- every installed revision stays + // usable, and a raised `revision` only changes what a new install gets + // (xpkg V2 spec, "floor"). A floor above the revision reads as the + // revision. + int floor = 0; // The oldest client that can use this version (`min_client = // "2026.10.16.1"`): a client resolving a package with no version named // passes over the versions it cannot use. Empty when the entry states none. diff --git a/tests/fixtures/pkgindex/pkgs/v/v2revision.lua b/tests/fixtures/pkgindex/pkgs/v/v2revision.lua index 5ff7614..e6db9e4 100644 --- a/tests/fixtures/pkgindex/pkgs/v/v2revision.lua +++ b/tests/fixtures/pkgindex/pkgs/v/v2revision.lua @@ -17,6 +17,7 @@ package = { url = "https://ex/v2revision-1.1.0.tar.gz", sha256 = "bbbb", revision = 2, + floor = 1, }, ["1.2.0"] = { x86_64 = { url = "https://ex/v2revision-1.2.0-x86_64.tar.gz", sha256 = "cccc" }, @@ -33,6 +34,12 @@ package = { sha256 = "ffff", revision = -1, }, + ["1.5.0"] = { + url = "https://ex/v2revision-1.5.0.tar.gz", + sha256 = "abab", + revision = 1, + floor = 4, + }, }, }, } diff --git a/tests/test_loader.cpp b/tests/test_loader.cpp index 337c73b..7433ade 100644 --- a/tests/test_loader.cpp +++ b/tests/test_loader.cpp @@ -397,6 +397,25 @@ TEST(LoaderTest, V2_Revision_ParsedPerVersionEntry) { EXPECT_EQ(plat.at("latest").ref, "1.2.0"); } +// `floor`: the oldest installed revision still usable. Absent is 0 (every +// installed revision stays usable); a floor above the revision reads as the +// revision, so a malformed entry never declares every payload unusable. +TEST(LoaderTest, V2_Floor_ParsedAndBoundedByRevision) { + auto result = load_package(PKGINDEX / "pkgs/v/v2revision.lua"); + ASSERT_TRUE(result.has_value()) << result.error(); + auto& plat = result->xpm.entries.at("linux"); + EXPECT_EQ(plat.at("1.0.0").floor, 0); + EXPECT_EQ(plat.at("1.1.0").floor, 1); + EXPECT_EQ(plat.at("1.2.0").floor, 0); + EXPECT_EQ(plat.at("1.5.0").floor, 1); // 4 > revision 1 + + auto direct = resolve_resource(result->xpm, { + .name = "v2revision", .version = "1.1.0", + .platform = "linux", .arch = "x86_64", .ext = ""}); + ASSERT_TRUE(direct.has_value()) << direct.error(); + EXPECT_EQ(direct->floor, 1); +} + // The resolver reports the revision of the entry that supplies the payload, // so a client asking for an alias learns the revision it will install. TEST(LoaderTest, V2_Revision_ResolvedThroughRef) {