@oj-module/cli 0.2.68 → 0.2.71

package/templates/tests/lifecycle/backfill.spec.ts

@@ -0,0 +1,392 @@
+// BDD：站点侧目录回填（计划 v4 §六——三用：回填=恢复=对账）。
+// POST /api/oj-market/backfill（superadmin，R9）：扫 cdn/ 存量 tgz → 内嵌 manifest 抽取
+// （与上传端点同一 manifestOfUpload 管线）+ 旁车 .sig（key_id/签名恢复）→ upsert
+// market_release。幂等可重入；无 CLI 依赖（远端纯站点经 HTTP 触发）。
+// 降级口径（数据表）：.sig 缺失/不可解析的行照常落库但 sig 四列 NULL（安装验签
+// sig_missing fail-closed）；坏包进 skipped 不阻断其它文件；已 yank 行不回魂。
+
+import type { FsFace } from "../../src/app/api/_platform/_lifecycle/atomic";
+import type { ExecFace } from "../../src/app/api/_platform/_lifecycle/steps/extract";
+import type { MarketEnv } from "../../src/oj-market/api/api";
+import { createHash } from "node:crypto";
+import * as fsp from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { defaultTestKey, nodeVerifyEd25519, signedArchiveFor } from "../../../src/lifecycle/__tests__/helpers";
+import { createMarketApi, marketEnv } from "../../src/oj-market/api/api";
+import { installDb } from "../fixture";
+
+const g = globalThis as any;
+
+// tgz「字节」即 `<name>|<version>` 文本：manifestOfUpload 的 staging 文件名是常量 upload.tgz，
+// tar stub 从 staged 字节读回 name/version（真实管道以包内 manifest 为真源，stub 同构模拟）。
+// 签名/哈希全按实写字节算，假 tar 不需要真归档格式。
+const TEST_KEY = defaultTestKey();
+function pkgBytes(name: string, version: string): Uint8Array {
+	return new TextEncoder().encode(`${name}|${version}\n`);
+}
+function shaOf(bytes: Uint8Array): string {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+
+/** 捕获 json.ok/json.fail 出口（respond 收口后恰一次调用） */
+let last: { status: number, msg?: string, data?: unknown } | null = null;
+
+function nodeFsFace(): FsFace {
+	return {
+		writeFile: (path, data) => fsp.writeFile(path, data),
+		readFile: path => fsp.readFile(path),
+		mkdir: (path, opts) => fsp.mkdir(path, opts),
+		remove: (path, opts) => fsp.rm(path, opts),
+		rename: (oldPath, newPath) => fsp.rename(oldPath, newPath),
+		copyFile: (src, dest) => fsp.copyFile(src, dest),
+		readdir: path => fsp.readdir(path),
+	};
+}
+
+/**
+ * tar stub：list 恒过；extract 从 staged 字节读回 `<name>|<version>` 写扁平 manifest.yaml。
+ *  「not-a-tar」字节模拟坏包（list 即失败）——staging 文件名是常量 upload.tgz，无法按名分流。
+ */
+function tarExec(manifestOverride?: (name: string, version: string) => Record<string, unknown>): ExecFace {
+	return {
+		run: async (argv) => {
+			if (argv[0] === "tar" && argv[1] === "-tvzf") {
+				const staged = await fsp.readFile(String(argv[2]), "utf-8");
+				if (staged === "not-a-tar")
+					return { code: 1, stdout: "", stderr: "garbage" };
+				return { code: 0, stdout: "manifest.yaml\n", stderr: "" };
+			}
+			if (argv[0] === "tar" && argv[1] === "-xzf") {
+				const dest = argv[4]!;
+				const [name = "demo-solution", version = "0.1.0"] = (await fsp.readFile(String(argv[2]), "utf-8")).split("|");
+				await fsp.mkdir(dest, { recursive: true });
+				await fsp.writeFile(join(dest, "manifest.yaml"), JSON.stringify(
+					manifestOverride?.(name, version) ?? { name, version: version.replace(/\n$/, ""), summary: "存量回填包" },
+				));
+				return { code: 0, stdout: "", stderr: "" };
+			}
+			return { code: 0, stdout: "", stderr: "" };
+		},
+	};
+}
+
+let root: string;
+let cdnDir: string;
+let staging: string;
+let dbPath: string;
+let dbo: any;
+
+function makeEnv(overrides: Partial<MarketEnv> = {}): MarketEnv {
+	return {
+		...marketEnv(),
+		sharedRoot: join(root, "dist", "api"),
+		staging,
+		taskDir: join(root, "modules", ".install-tasks"),
+		statePath: join(root, ".solutions", "state.yaml"),
+		trustPath: join(root, ".solutions", "trusted-keys.yaml"),
+		dbPath,
+		siteModulesDir: join(root, "dist", "web", "modules"),
+		modulesJsonPath: join(root, "dist", "web", "modules.json"),
+		cdnDir,
+		exec: tarExec(),
+		sha256Hex: d => createHash("sha256").update(d).digest("hex"),
+		verifyEd25519: nodeVerifyEd25519,
+		...overrides,
+	} as MarketEnv;
+}
+
+/** cdn/ 落一个存量包：tgz 字节（`<name>|<version>`）+ 可选 .sig 旁车（六字段） */
+async function dropCdnPackage(name: string, version: string, opts: { sig?: boolean, bytes?: Uint8Array } = {}): Promise<Uint8Array> {
+	const bytes = opts.bytes ?? pkgBytes(name, version);
+	await fsp.writeFile(join(cdnDir, `${name}-${version}.tgz`), bytes);
+	if (opts.sig !== false) {
+		const sig = signedArchiveFor(bytes, name, version, { keyPair: TEST_KEY }).sig;
+		await fsp.writeFile(join(cdnDir, `${name}-${version}.tgz.sig`), JSON.stringify(sig));
+	}
+	return bytes;
+}
+
+function rows(): Array<Record<string, unknown>> {
+	return dbo.prepare("SELECT * FROM market_release ORDER BY product, version").all();
+}
+
+beforeEach(async () => {
+	root = await fsp.mkdtemp(join(tmpdir(), "ojm-backfill-"));
+	cdnDir = join(root, "cdn");
+	staging = join(root, "modules", ".staging");
+	dbPath = join(root, "db.sqlite");
+	await fsp.mkdir(cdnDir, { recursive: true });
+	await fsp.writeFile(dbPath, new TextEncoder().encode("sqlite-header\n"));
+	g.fs = nodeFsFace();
+	dbo = installDb();
+	dbo.prepare("INSERT OR IGNORE INTO sys_user_role (user_id, role_name) VALUES (?, ?)").run(1, "superadmin");
+	g.yaml = { parse: async (t: string) => JSON.parse(t) };
+	g.http = { user: { id: 1 } };
+	g.json = {
+		ok: (data: unknown) => {
+			last = { status: 200, data };
+		},
+		fail: (status: number, msg: string) => {
+			last = { status, msg };
+		},
+		header: () => {},
+	};
+	last = null;
+});
+
+afterEach(async () => {
+	g.fs = undefined;
+	g.http = undefined;
+	g.json = undefined;
+	g.yaml = undefined;
+	g.db = undefined;
+	await fsp.rm(root, { recursive: true, force: true });
+});
+
+describe("场景：回填（cdn/ 存量 → DB 目录行）", () => {
+	it("给定 存量 tgz+.sig 无 DB 行，当 回填，则 行落库：published_at_source='file'、sig 四列取旁车", async () => {
+		const bytes = await dropCdnPackage("demo-solution", "0.1.0");
+		const api = createMarketApi(makeEnv());
+		await api.backfill.post();
+		expect(last?.status).toBe(200);
+		const rs = rows();
+		expect(rs).toHaveLength(1);
+		expect(rs[0]).toMatchObject({
+			product: "demo-solution",
+			version: "0.1.0",
+			key_id: "test.publisher",
+			sha256: shaOf(bytes),
+			size: bytes.byteLength,
+			published_at_source: "file",
+			yanked: 0,
+		});
+		expect(String(rs[0]!.sig_alg)).toBe("Ed25519");
+		expect(typeof rs[0]!.sig_value).toBe("string");
+		expect(typeof rs[0]!.sig_registry_id).toBe("string");
+		const report = last?.data as { scanned: number, upserted: number, sigMissing: string[] };
+		expect(report).toMatchObject({ scanned: 1, upserted: 1, sigMissing: [] });
+	});
+
+	it("数据表 .sig 缺失降级：行照落库，sig 四列 NULL，文件名进 sigMissing", async () => {
+		await dropCdnPackage("demo-solution", "0.1.0", { sig: false });
+		const api = createMarketApi(makeEnv());
+		await api.backfill.post();
+		expect(last?.status).toBe(200);
+		const rs = rows();
+		expect(rs).toHaveLength(1);
+		expect(rs[0]).toMatchObject({ sig_alg: null, sig_value: null, sig_public_key: null, sig_registry_id: null, key_id: null });
+		expect((last?.data as { sigMissing: string[] }).sigMissing).toEqual(["demo-solution-0.1.0.tgz"]);
+	});
+
+	it("数据表 旁车验签失败（形全但 sha 与字节不绑定，投毒旁车）：行照落库，sig 四列 NULL，进 sigMissing（fail-closed 与缺签同口径）", async () => {
+		const bytes = pkgBytes("demo-solution", "0.1.0");
+		// 形全实毒：对其它字节按同名同版本签出——结构合法、签名有效，唯与实收字节无绑定
+		const poisoned = signedArchiveFor(pkgBytes("evil", "9.9.9"), "demo-solution", "0.1.0", { keyPair: TEST_KEY });
+		await fsp.writeFile(join(cdnDir, "demo-solution-0.1.0.tgz"), bytes);
+		await fsp.writeFile(join(cdnDir, "demo-solution-0.1.0.tgz.sig"), JSON.stringify(poisoned.sig));
+		const api = createMarketApi(makeEnv());
+		await api.backfill.post();
+		expect(last?.status).toBe(200);
+		const rs = rows();
+		expect(rs).toHaveLength(1);
+		expect(rs[0]).toMatchObject({ sig_alg: null, sig_value: null, sig_public_key: null, sig_registry_id: null, key_id: null, sha256: shaOf(bytes) });
+		expect((last?.data as { sigMissing: string[] }).sigMissing).toEqual(["demo-solution-0.1.0.tgz"]);
+	});
+});
+
+describe("场景：幂等可重入（对账）", () => {
+	it("给定 已回填，当 重跑，则 行数不变、upserted=0、published_at 等审计列不被改写", async () => {
+		await dropCdnPackage("demo-solution", "0.1.0");
+		const api = createMarketApi(makeEnv());
+		await api.backfill.post();
+		const before = rows();
+		await api.backfill.post();
+		const report = last?.data as { upserted: number, unchanged: number };
+		expect(report).toMatchObject({ upserted: 0, unchanged: 1 });
+		expect(rows()).toEqual(before);
+	});
+
+	it("给定 遗留行（sig 列 NULL、published_at 旧值、yanked=1），当 回填，则 sig 列补齐且 published_at/first_seen_at/yanked 原样保留（yank 不回魂）", async () => {
+		await dropCdnPackage("demo-solution", "0.1.0");
+		dbo.prepare("INSERT INTO market_release (product,version,key_id,sha256,size,published_at,published_at_source,yanked,first_seen_at,sig_alg,sig_value,sig_public_key,sig_registry_id,manifest) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)")
+			.run("demo-solution", "0.1.0", null, "old-sha", 1, 424242, "file", 1, 424242, null, null, null, null, null);
+		const api = createMarketApi(makeEnv());
+		await api.backfill.post();
+		expect(last?.status).toBe(200);
+		const rs = rows();
+		expect(rs).toHaveLength(1);
+		expect(rs[0]).toMatchObject({
+			sha256: shaOf(pkgBytes("demo-solution", "0.1.0")),
+			published_at: 424242,
+			first_seen_at: 424242,
+			yanked: 1,
+			key_id: "test.publisher",
+		});
+		expect(String(rs[0]!.sig_alg)).toBe("Ed25519");
+	});
+});
+
+describe("场景：灾备恢复（清表 → 扫描恢复）", () => {
+	it("给定 表清空 cdn/ 完好，当 回填，则 行恢复且重复跑行数不变", async () => {
+		await dropCdnPackage("demo-solution", "0.1.0");
+		await dropCdnPackage("other-solution", "2.0.0");
+		const api = createMarketApi(makeEnv());
+		await api.backfill.post();
+		dbo.prepare("DELETE FROM market_release").run();
+		await api.backfill.post();
+		expect(rows()).toHaveLength(2);
+		await api.backfill.post();
+		expect(rows()).toHaveLength(2);
+	});
+});
+
+describe("场景：门禁与坏包分流", () => {
+	it("数据表 角色门禁：匿名 401 / 非 superadmin 403", async () => {
+		const api = createMarketApi(makeEnv());
+		g.http = {};
+		await api.backfill.post();
+		expect(last?.status).toBe(403); // assertSuperAdmin 对匿名亦 403（不泄露存在性）
+		g.http = { user: { id: 2 } };
+		await api.backfill.post();
+		expect(last?.status).toBe(403);
+	});
+
+	it("给定 坏包与好包并存，当 回填，则 坏包进 skipped 带 reason、好包照落库", async () => {
+		await dropCdnPackage("good-solution", "0.1.0");
+		await fsp.writeFile(join(cdnDir, "broken-9.9.9.tgz"), new TextEncoder().encode("not-a-tar"));
+		const api = createMarketApi(makeEnv({ exec: tarExec() }));
+		await api.backfill.post();
+		expect(last?.status).toBe(200);
+		expect(rows()).toHaveLength(1);
+		const report = last?.data as { skipped: Array<{ file: string, reason: string }> };
+		expect(report.skipped).toHaveLength(1);
+		expect(report.skipped[0]!.file).toBe("broken-9.9.9.tgz");
+		expect(report.skipped[0]!.reason).toContain("列表失败");
+	});
+
+	it("给定 manifest 名实不符（文件名 demo-a、包内 manifest name=demo-b），当 回填，则 跳过并给出 reason", async () => {
+		await dropCdnPackage("demo-a", "0.1.0");
+		// 包内 manifest 写 demo-b → 与文件名 demo-a 名实不符
+		const api = createMarketApi(makeEnv({ exec: tarExec(() => ({ name: "demo-b", version: "0.1.0" })) }));
+		await api.backfill.post();
+		expect(rows()).toHaveLength(0);
+		const report = last?.data as { skipped: Array<{ file: string, reason: string }> };
+		expect(report.skipped[0]!.reason).toContain("名实不符");
+	});
+
+	it("数据表 并发撞唯一键（select 与 insert 之间他方上传先落行，异字节）：该文件进 skipped 带冲突 reason，好包照常落库，扫描不中断（minor M2）", async () => {
+		await dropCdnPackage("race-solution", "0.1.0");
+		await dropCdnPackage("good-solution", "0.1.0");
+		// 拦截 market_release 的 insert：真正写入前先经裸 SQL 落一行他方并发行（异字节）→ 原 insert 撞唯一键
+		const origTable = g.db.table.bind(g.db);
+		let armed = true;
+		g.db.table = (name: string) => {
+			const t = origTable(name);
+			if (name !== "market_release" || !armed)
+				return t;
+			return new Proxy(t, {
+				get(target, prop) {
+					if (prop === "insert") {
+						return (row: { product?: string }) => ({
+							run: async () => {
+								if (row.product === "race-solution" && armed) {
+									armed = false;
+									dbo.prepare("INSERT INTO market_release (product,version,key_id,sha256,size,published_at,published_at_source,yanked,first_seen_at) VALUES (?,?,?,?,?,?,?,?,?)")
+										.run("race-solution", "0.1.0", "other.publisher", "racedeadbeef", 9, 1000, "upload", 0, 1000);
+								}
+								return target.insert(row).run(); // race 文件撞 (product,version) 唯一键抛错
+							},
+						});
+					}
+					const v = (target as never)[prop as never];
+					return typeof v === "function" ? v.bind(target) : v;
+				},
+			});
+		};
+		const api = createMarketApi(makeEnv());
+		await api.backfill.post();
+		g.db.table = origTable;
+		expect(last?.status).toBe(200);
+		// 好包照常落库；race 文件 skipped（reason 含冲突），全量扫描不中断
+		expect(rows().map(r => r.product).sort()).toEqual(["good-solution", "race-solution"]);
+		const report = last?.data as { skipped: Array<{ file: string, reason: string }>, scanned: number };
+		expect(report.scanned).toBe(2);
+		expect(report.skipped).toHaveLength(1);
+		expect(report.skipped[0]!.file).toBe("race-solution-0.1.0.tgz");
+		expect(String(report.skipped[0]!.reason)).toContain("冲突");
+		// 他方并发行原样保留（不被回填改写）
+		const raced = dbo.prepare("SELECT sha256 FROM market_release WHERE product='race-solution'").get();
+		expect(raced.sha256).toBe("racedeadbeef");
+	});
+
+	it("数据表 并发撞唯一键但同字节（他方上传同内容）：幂等判 unchanged，不重复落库（minor M2 同字节支路）", async () => {
+		const bytes = await dropCdnPackage("same-solution", "0.1.0");
+		const sha = shaOf(bytes);
+		const racedSig = signedArchiveFor(bytes, "same-solution", "0.1.0", { keyPair: TEST_KEY }).sig;
+		const racedManifest = JSON.stringify({ name: "same-solution", version: "0.1.0", summary: "存量回填包" });
+		const origTable = g.db.table.bind(g.db);
+		let armed = true;
+		g.db.table = (name: string) => {
+			const t = origTable(name);
+			if (name !== "market_release" || !armed)
+				return t;
+			return new Proxy(t, {
+				get(target, prop) {
+					if (prop === "insert") {
+						return (row: unknown) => ({
+							run: async () => {
+								armed = false;
+								dbo.prepare("INSERT INTO market_release (product,version,key_id,sha256,size,published_at,published_at_source,yanked,first_seen_at,sig_alg,sig_value,sig_public_key,sig_registry_id,manifest) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)")
+									.run("same-solution", "0.1.0", racedSig.key_id, sha, bytes.byteLength, 1000, "upload", 0, 1000, racedSig.alg, racedSig.value, racedSig.public_key, racedSig.registry_id, racedManifest);
+								return target.insert(row).run();
+							},
+						});
+					}
+					const v = (target as never)[prop as never];
+					return typeof v === "function" ? v.bind(target) : v;
+				},
+			});
+		};
+		const api = createMarketApi(makeEnv());
+		await api.backfill.post();
+		g.db.table = origTable;
+		expect(last?.status).toBe(200);
+		expect(rows()).toHaveLength(1);
+		const report = last?.data as { unchanged: number, upserted: number };
+		expect(report).toMatchObject({ unchanged: 1, upserted: 0 });
+	});
+
+	it("数据表 insert 底层错误（非撞键，如 DB 故障）：原样上抛不吞（minor M2 不遮真故障）", async () => {
+		await dropCdnPackage("demo-solution", "0.1.0");
+		const origTable = g.db.table.bind(g.db);
+		g.db.table = (name: string) => {
+			const t = origTable(name);
+			if (name !== "market_release")
+				return t;
+			return new Proxy(t, {
+				get(target, prop) {
+					if (prop === "insert")
+						return () => ({ run: async () => { throw new Error("SQLITE_ERROR: disk I/O error"); } });
+					const v = (target as never)[prop as never];
+					return typeof v === "function" ? v.bind(target) : v;
+				},
+			});
+		};
+		const api = createMarketApi(makeEnv());
+		await api.backfill.post();
+		g.db.table = origTable;
+		expect(last?.status).toBe(500);
+		expect(rows()).toHaveLength(0);
+	});
+
+	it("给定 孤立 .sig（tgz 缺失），当 回填，则 忽略不报错（容忍口径，不加 GC）", async () => {
+		await fsp.writeFile(join(cdnDir, "lonely-1.0.0.tgz.sig"), "{}");
+		const api = createMarketApi(makeEnv());
+		await api.backfill.post();
+		expect(last?.status).toBe(200);
+		expect(rows()).toHaveLength(0);
+		expect((last?.data as { scanned: number }).scanned).toBe(0);
+	});
+});

package/templates/tests/lifecycle/bootstrap.spec.ts

@@ -12,7 +12,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { createTrustStore } from "../../src/app/api/_platform/_lifecycle/trust";
-import { BOOTSTRAP_KEY, seedBootstrapKey } from "../../src/app/api/_platform/market/bootstrap";
+import { BOOTSTRAP_KEY, seedBootstrapKey } from "../../src/oj-market/api/bootstrap";
 
 const g = globalThis as any;
 

package/templates/tests/lifecycle/bundle-converge.spec.ts

@@ -0,0 +1,264 @@
+// BDD：随站 bundle 启动收敛（Phase B T3b）——`ojm init --yes` 把第一方 oj-market
+// 包落位 cdn/ 并写意图标记（bundles.json），站点侧幂等对账（方案 §5「上拉不下拉」）：
+//   未装 → 安装；bundle > 已装 → 升级；bundle ≤ 已装 → 跳过（市场轨升过不降级，
+//   对齐 rollbackGuard 禁降版红线 OJ-9）；任一失败 → 记 failed 续跑，不阻断消费面。
+// 挂点说明：oj 启动段 ext_boot 有 2s 看门狗（oj-bin runtime.rs BOOT_TIMEOUT），
+// 安装全程不可在 boot 内跑——收敛执行 riding 首个编排 API 请求（index 端点对账即
+// 服务先例），本模块对调用方只暴露「跑一遍对账」的纯编排。
+import type { FsFace } from "../../src/app/api/_platform/_lifecycle/atomic";
+import type { SidecarSig } from "../../src/oj-market/api/cdn/shared";
+import * as fsp from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { bundleConvergePlan, convergeBundledSolutions } from "../../src/app/api/_platform/_lifecycle/bundle-converge";
+import { createStateStore } from "../../src/app/api/_platform/_lifecycle/state";
+
+const g = globalThis as any;
+
+function nodeFsFace(): FsFace {
+	return {
+		writeFile: (path, data) => fsp.writeFile(path, data),
+		readFile: path => fsp.readFile(path),
+		mkdir: (path, opts) => fsp.mkdir(path, opts),
+		remove: (path, opts) => fsp.rm(path, opts),
+		rename: (oldPath, newPath) => fsp.rename(oldPath, newPath),
+		copyFile: (src, dest) => fsp.copyFile(src, dest),
+		readdir: path => fsp.readdir(path),
+	};
+}
+
+describe("bundle 启动收敛：上拉不下拉", () => {
+	it("未装（null）→ install", () => {
+		expect(bundleConvergePlan(null, "0.2.0")).toBe("install");
+	});
+
+	it("已装 v1，bundle v2 → upgrade", () => {
+		expect(bundleConvergePlan("0.1.0", "0.2.0")).toBe("upgrade");
+	});
+
+	it("同版本 → skip（幂等）", () => {
+		expect(bundleConvergePlan("0.2.0", "0.2.0")).toBe("skip");
+	});
+
+	it("已装 v3（市场轨升的）, bundle v2 → skip（不降级，OJ-9 同源）", () => {
+		expect(bundleConvergePlan("0.3.0", "0.2.0")).toBe("skip");
+	});
+});
+
+describe("bundle 启动收敛：执行编排（真实 marker/cdn/状态文件 + installLocal 注入）", () => {
+	let root: string;
+	let cdnDir: string;
+	let statePath: string;
+	let markerPath: string;
+	const installLocal = vi.fn<(entry: { name: string, version: string, file: string }, archive: { bytes: Uint8Array, sig: SidecarSig | null }) => Promise<void>>();
+
+	async function seedMarker(entries: unknown): Promise<void> {
+		await fsp.writeFile(markerPath, JSON.stringify({ solutions: entries }));
+	}
+
+	beforeEach(async () => {
+		root = await fsp.mkdtemp(join(tmpdir(), "ojm-bundle-converge-"));
+		cdnDir = join(root, "cdn");
+		statePath = join(root, ".solutions", "state.yaml");
+		markerPath = join(cdnDir, "bundles.json");
+		await fsp.mkdir(cdnDir, { recursive: true });
+		await fsp.mkdir(join(root, ".solutions"), { recursive: true });
+		g.fs = nodeFsFace();
+		installLocal.mockReset();
+	});
+
+	afterEach(async () => {
+		g.fs = undefined;
+		await fsp.rm(root, { recursive: true, force: true });
+	});
+
+	const env = () => ({ markerPath, cdnDir, statePath, installLocal });
+
+	it("marker 缺失 → 零动作安静返回（无 bundle 的站点/旧工程）", async () => {
+		const r = await convergeBundledSolutions(env());
+		expect(r).toEqual({ installed: [], upgraded: [], skipped: [], failed: [], cooling: [] });
+		expect(installLocal).not.toHaveBeenCalled();
+	});
+
+	it("未装 → 读 cdn 字节与旁车，installLocal 收 install 计划", async () => {
+		await seedMarker([{ name: "oj-market", version: "0.2.0", file: "oj-market-0.2.0.tgz" }]);
+		await fsp.writeFile(join(cdnDir, "oj-market-0.2.0.tgz"), new Uint8Array([1, 2, 3]));
+		await fsp.writeFile(join(cdnDir, "oj-market-0.2.0.tgz.sig"), JSON.stringify({ alg: "Ed25519", key_id: "platform.release", public_key: "ab".repeat(32), value: "AQID", canon: "v2", registry_id: "oj-registry" }));
+		const r = await convergeBundledSolutions(env());
+		expect(r.installed).toEqual(["oj-market@0.2.0"]);
+		expect(installLocal).toHaveBeenCalledTimes(1);
+		const [entry, archive] = installLocal.mock.calls[0]!;
+		expect(entry).toEqual({ name: "oj-market", version: "0.2.0", file: "oj-market-0.2.0.tgz" });
+		expect(archive.bytes).toEqual(new Uint8Array([1, 2, 3]));
+		expect(archive.sig?.key_id).toBe("platform.release");
+	});
+
+	it("已装 v1、bundle v2 → upgrade；另一产品同版 → skip", async () => {
+		await seedMarker([
+			{ name: "oj-market", version: "0.2.0", file: "oj-market-0.2.0.tgz" },
+			{ name: "wiki", version: "1.0.0", file: "wiki-1.0.0.tgz" },
+		]);
+		await fsp.writeFile(join(cdnDir, "oj-market-0.2.0.tgz"), new Uint8Array([1]));
+		await fsp.writeFile(join(cdnDir, "wiki-1.0.0.tgz"), new Uint8Array([2]));
+		await (await createStateStore(statePath)).write({ solutions: {
+			"oj-market": { version: "0.1.0", enabled: true, installedAt: 0 },
+			"wiki": { version: "1.0.0", enabled: true, installedAt: 0 },
+		} });
+		const r = await convergeBundledSolutions(env());
+		expect(r.upgraded).toEqual(["oj-market@0.2.0"]);
+		expect(r.skipped).toEqual(["wiki@1.0.0"]);
+		expect(installLocal).toHaveBeenCalledTimes(1);
+	});
+
+	it("已装 v3（市场轨）> bundle v2 → skip，installLocal 零调用（不降级）", async () => {
+		await seedMarker([{ name: "oj-market", version: "0.2.0", file: "oj-market-0.2.0.tgz" }]);
+		await (await createStateStore(statePath)).write({ solutions: { "oj-market": { version: "0.3.0", enabled: true, installedAt: 0 } } });
+		const r = await convergeBundledSolutions(env());
+		expect(r.skipped).toEqual(["oj-market@0.2.0"]);
+		expect(installLocal).not.toHaveBeenCalled();
+	});
+
+	it("installLocal 抛错 → 记 failed 且续跑后续条目（降级不阻断）", async () => {
+		await seedMarker([
+			{ name: "oj-market", version: "0.2.0", file: "oj-market-0.2.0.tgz" },
+			{ name: "oj-market", version: "0.2.0", file: "oj-market-0.2.0.tgz" },
+		]);
+		await fsp.writeFile(join(cdnDir, "oj-market-0.2.0.tgz"), new Uint8Array([1]));
+		installLocal.mockRejectedValueOnce(new Error("验签失败"));
+		const r = await convergeBundledSolutions(env());
+		expect(r.failed).toEqual(["oj-market@0.2.0（验签失败）"]);
+		expect(r.installed).toEqual(["oj-market@0.2.0"]);
+		expect(installLocal).toHaveBeenCalledTimes(2);
+	});
+
+	it("旁车缺失 → sig 传 null（无签名包交安装器 verify 六码分流，不本地预判）", async () => {
+		await seedMarker([{ name: "oj-market", version: "0.2.0", file: "oj-market-0.2.0.tgz" }]);
+		await fsp.writeFile(join(cdnDir, "oj-market-0.2.0.tgz"), new Uint8Array([1]));
+		await convergeBundledSolutions(env());
+		expect(installLocal.mock.calls[0]![1].sig).toBeNull();
+	});
+});
+
+describe("bundle 收敛：卸载墓碑（终审 Important-1）", () => {
+	let root: string;
+
+	beforeEach(async () => {
+		root = await fsp.mkdtemp(join(tmpdir(), "ojm-bundle-prune-"));
+		g.fs = nodeFsFace();
+	});
+
+	afterEach(async () => {
+		g.fs = undefined;
+		await fsp.rm(root, { recursive: true, force: true });
+	});
+
+	it("pruneBundledMarker：摘除指定条目、其余保留；marker 缺失/损坏安静 no-op", async () => {
+		const { pruneBundledMarker } = await import("../../src/app/api/_platform/_lifecycle/bundle-converge");
+		const marker = join(root, "bundles.json");
+		await fsp.writeFile(marker, JSON.stringify({ solutions: [
+			{ name: "oj-market", version: "0.2.0", file: "oj-market-0.2.0.tgz" },
+			{ name: "wiki", version: "1.0.0", file: "wiki-1.0.0.tgz" },
+		] }));
+		await pruneBundledMarker(marker, "oj-market");
+		const after = JSON.parse(await fsp.readFile(marker, "utf-8"));
+		expect(after.solutions).toEqual([{ name: "wiki", version: "1.0.0", file: "wiki-1.0.0.tgz" }]);
+		// 幂等：再摘同名（条目已不在）不报错
+		await pruneBundledMarker(marker, "oj-market");
+		// marker 缺失 no-op
+		await pruneBundledMarker(join(root, "nope.json"), "oj-market");
+	});
+
+	it("卸载摘碑后收敛不再自动重装（installLocal 零调用）", async () => {
+		const { pruneBundledMarker } = await import("../../src/app/api/_platform/_lifecycle/bundle-converge");
+		const cdnDir = join(root, "cdn");
+		const statePath = join(root, ".solutions", "state.yaml");
+		const markerPath = join(cdnDir, "bundles.json");
+		await fsp.mkdir(cdnDir, { recursive: true });
+		await fsp.mkdir(join(root, ".solutions"), { recursive: true });
+		await fsp.writeFile(markerPath, JSON.stringify({ solutions: [{ name: "oj-market", version: "0.2.0", file: "oj-market-0.2.0.tgz" }] }));
+		await fsp.writeFile(join(cdnDir, "oj-market-0.2.0.tgz"), new Uint8Array([1]));
+		const installLocal = vi.fn(async () => {});
+		// 未装 → 装
+		const cdnDirArg = cdnDir;
+		const r1 = await convergeBundledSolutions({ markerPath, cdnDir: cdnDirArg, statePath, installLocal });
+		expect(r1.installed).toEqual(["oj-market@0.2.0"]);
+		// 卸载 = 摘碑（端点侧 runUninstall 成功后调用；状态条目由卸载面清除，此处模拟无条目）
+		await pruneBundledMarker(markerPath, "oj-market");
+		const r2 = await convergeBundledSolutions({ markerPath, cdnDir: cdnDirArg, statePath, installLocal });
+		expect(r2).toEqual({ installed: [], upgraded: [], skipped: [], failed: [], cooling: [] });
+		expect(installLocal).toHaveBeenCalledTimes(1);
+	});
+});
+
+describe("bundle 收敛：失败冷却（终审 Important-2）", () => {
+	let root: string;
+	let cdnDir: string;
+	let statePath: string;
+	let markerPath: string;
+	let cooldownPath: string;
+	const installLocal = vi.fn<(entry: { name: string, version: string, file: string }, archive: { bytes: Uint8Array, sig: unknown | null }) => Promise<void>>();
+
+	const env = (now: () => number) => ({
+		markerPath,
+		cdnDir,
+		statePath,
+		installLocal,
+		cooldownPath,
+		now,
+	});
+
+	beforeEach(async () => {
+		root = await fsp.mkdtemp(join(tmpdir(), "ojm-bundle-cooldown-"));
+		cdnDir = join(root, "cdn");
+		statePath = join(root, ".solutions", "state.yaml");
+		markerPath = join(cdnDir, "bundles.json");
+		cooldownPath = join(root, ".converge-cooldown.json");
+		await fsp.mkdir(cdnDir, { recursive: true });
+		await fsp.mkdir(join(root, ".solutions"), { recursive: true });
+		await fsp.writeFile(markerPath, JSON.stringify({ solutions: [{ name: "oj-market", version: "0.2.0", file: "oj-market-0.2.0.tgz" }] }));
+		await fsp.writeFile(join(cdnDir, "oj-market-0.2.0.tgz"), new Uint8Array([1]));
+		g.fs = nodeFsFace();
+		installLocal.mockReset();
+	});
+
+	afterEach(async () => {
+		g.fs = undefined;
+		await fsp.rm(root, { recursive: true, force: true });
+	});
+
+	it("失败后在冷却窗内不再重试（cooling 桶），出窗恢复重试；成功清除冷却", async () => {
+		let t = 1_000_000;
+		installLocal.mockRejectedValueOnce(new Error("验签失败"));
+		const r1 = await convergeBundledSolutions(env(() => t));
+		expect(r1.failed).toHaveLength(1);
+		// 窗内（10 分钟 = 600_000ms）：cooling，installLocal 不再被调
+		t += 60_000;
+		const r2 = await convergeBundledSolutions(env(() => t));
+		expect(r2.cooling).toEqual(["oj-market@0.2.0"]);
+		expect(installLocal).toHaveBeenCalledTimes(1);
+		// 出窗：重试并成功 → 冷却清除；此后同版本 skip
+		t += 600_000;
+		const r3 = await convergeBundledSolutions(env(() => t));
+		expect(r3.installed).toEqual(["oj-market@0.2.0"]);
+		expect(installLocal).toHaveBeenCalledTimes(2);
+		// 成功清除冷却：冷却文件已无该键
+		const cd = JSON.parse(await fsp.readFile(cooldownPath, "utf-8"));
+		expect(cd).toEqual({});
+	});
+
+	it("无 cooldownPath（调用方不启用）→ 行为与既有口径一致（全部进 failed 重试）", async () => {
+		let calls = 0;
+		installLocal.mockImplementation(async () => {
+			calls++;
+			throw new Error("boom");
+		});
+		const envNoCd = () => ({ markerPath, cdnDir, statePath, installLocal });
+		await convergeBundledSolutions(envNoCd());
+		const r2 = await convergeBundledSolutions(envNoCd());
+		expect(r2.failed).toHaveLength(1);
+		expect(calls).toBe(2);
+	});
+});