@oj-module/cli 0.2.66 → 0.2.67

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

@@ -0,0 +1,207 @@
+// BDD：安装补偿清单（P0 §3.5）。锁后失败把站点恢复到「装前代」——旧代继续服务、任务 partial+可重试。
+// 直接驱动 compensate()（不重跑整个状态机），配真实内存库夹具（installDb）+ 真实临时文件系统 +
+// stub reload 面，覆盖：完整回滚、幂等、部分失败仍尽力回滚、匿名面不随失败放大（验收 4）。
+//
+// 资产回滚原语：removeAnonymousPaths（text-edit）/ revertLock（lock）/ removeModulesJsonEntry
+// （deploy-web）/ revertRegistrations（uninstall，复用卸载事务）。各原语幂等（缺则 no-op），
+// 故补偿可安全被重试端点反复调用。
+
+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 { atomicWriteText } from "../../src/app/api/_platform/_lifecycle/atomic";
+import { compensate } from "../../src/app/api/_platform/_lifecycle/compensate";
+import { parseLock, writeLock } from "../../src/app/api/_platform/_lifecycle/lock";
+import { appendAnonymousPaths, removeAnonymousPaths } from "../../src/app/api/_platform/_lifecycle/text-edit";
+import { installDb } from "../fixture";
+
+const g = globalThis as any;
+
+const BASE_CONFIG = "mounts: []\nserver:\n  reload_api: true\nvars:\n  other: 1\nauth:\n  anonymous_paths:\n    - /auth/login\n    - /system/login-methods\n";
+
+function nodeFsFace() {
+	return {
+		writeFile: (p: string, d: any) => fsp.writeFile(p, d),
+		readFile: (p: string) => fsp.readFile(p),
+		mkdir: (p: string, o: any) => fsp.mkdir(p, o),
+		remove: (p: string, o: any) => fsp.rm(p, o),
+		rename: (o: string, n: string) => fsp.rename(o, n),
+		copyFile: (s: string, d: string) => fsp.copyFile(s, d),
+		readdir: (p: string) => fsp.readdir(p),
+	};
+}
+
+let root: string;
+let configPath: string;
+let previewPath: string;
+let sharedRoot: string;
+let lockPath: string;
+let modulesJsonPath: string;
+let dbo: any;
+let reloadCalls: number;
+let reloadThrow: boolean;
+
+const LOCK_BEFORE: Record<string, string> = { existing: "1.0.0" };
+
+/** 把站点摆成「demo-solution 已锁后落位」状态，返回本次新增的匿名路径（= 补偿的输入 deferredAnonymous） */
+async function seedInstalled(anonPaths: string[]): Promise<string[]> {
+	const added = appendAnonymousPaths(BASE_CONFIG, anonPaths);
+	await atomicWriteText(configPath, added.content);
+	await atomicWriteText(previewPath, added.content);
+	// 锁：装前快照 + 本次模块条目
+	await writeLock(lockPath, { ...LOCK_BEFORE, "demo-solution": "0.1.0" });
+	// modules.json：含本次模块条目
+	await atomicWriteText(modulesJsonPath, `${JSON.stringify([{ name: "demo-solution", entry: "modules/demo-solution/0.1.0/entry.js", enabled: true }], null, 2)}\n`);
+	// DB：路由/角色/权限各一行为 demo-solution（registering 段已落位）
+	await g.db.table("sys_solution_route").insert({ path: "/demo-solution", module: "demo-solution", category: "main" }).run();
+	await g.db.table("sys_role").insert({ name: "demo-solution.admin", module: "demo-solution" }).run();
+	await g.db.table("sys_permission").insert({ code: "demo-solution.view", module: "demo-solution" }).run();
+	return added.added;
+}
+
+function countAnon(cfg: string): number {
+	const lines = cfg.split("\n");
+	const idx = lines.findIndex(l => /^\s*anonymous_paths\s*:/.test(l));
+	if (idx === -1)
+		return 0;
+	let n = 0;
+	for (let i = idx + 1; i < lines.length; i++) {
+		const line = lines[i]!;
+		if (line.trim() === "" || /^\s*#/.test(line))
+			continue;
+		if (!line.replace(/#.*$/, "").trim().startsWith("- "))
+			break;
+		n++;
+	}
+	return n;
+}
+
+beforeEach(async () => {
+	root = await fsp.mkdtemp(join(tmpdir(), "ojm-compensate-"));
+	configPath = join(root, "config.yaml");
+	previewPath = join(root, ".ojm-preview.yaml");
+	sharedRoot = join(root, "modules");
+	lockPath = join(sharedRoot, "manifests.yaml");
+	modulesJsonPath = join(root, "dist", "modules.json");
+	await fsp.mkdir(sharedRoot, { recursive: true });
+	await fsp.mkdir(join(root, "dist"), { recursive: true });
+	g.fs = nodeFsFace();
+	g.yaml = { parse: async (t: string) => JSON.parse(t) };
+	g.http = {};
+	dbo = installDb();
+	reloadCalls = 0;
+	reloadThrow = false;
+});
+
+afterEach(async () => {
+	g.fs = undefined;
+	g.http = undefined;
+	g.db = undefined;
+	await fsp.rm(root, { recursive: true, force: true });
+});
+
+function makeInput(deferredAnonymous: string[]): any {
+	return {
+		name: "demo-solution",
+		version: "0.1.0",
+		configPath,
+		deferredAnonymous,
+		sharedRoot,
+		modulesJsonPath,
+		lockBefore: LOCK_BEFORE,
+		lockExisted: true,
+		reload: {
+			reloadConfig: async () => {
+				reloadCalls++;
+				if (reloadThrow)
+					throw new Error("reload 模拟失败");
+				return { generation: 2, unchanged: false, applied: ["vars"], restart_pending: [], kept_listener: [] };
+			},
+		},
+	};
+}
+
+describe("compensate 完整回滚到装前代", () => {
+	it("锁/config匿名/modules.json/DB 全部回退，旧代仍服务（reload 已调用）", async () => {
+		const added = await seedInstalled(["demo-solution/ping", "demo-solution/health"]);
+		const r = await compensate(makeInput(added));
+
+		expect(r.allOk).toBe(true);
+		expect(r.steps.map(s => s.step)).toEqual(["config.anonymous", "lock", "modules.json", "db.registrations", "reload"]);
+
+		// 锁回到装前快照（无 demo-solution）
+		expect(parseLock(await fsp.readFile(lockPath, "utf8"))).toEqual(LOCK_BEFORE);
+		// config：新增匿名条目被精确移除，基线两条保留；seq 不被回滚（单调无害）
+		const cfg = await fsp.readFile(configPath, "utf8");
+		expect(cfg).toContain("- /auth/login");
+		expect(cfg).toContain("- /system/login-methods");
+		expect(cfg).not.toContain("demo-solution/ping");
+		expect(cfg).not.toContain("demo-solution/health");
+		expect(countAnon(cfg)).toBe(2);
+		// preview 派生同样被清理
+		const prev = await fsp.readFile(previewPath, "utf8");
+		expect(prev).not.toContain("demo-solution/ping");
+		// modules.json 无 demo-solution 条目
+		const list = JSON.parse(await fsp.readFile(modulesJsonPath, "utf8")) as unknown[];
+		expect(list.some((e: any) => e.name === "demo-solution")).toBe(false);
+		// DB 注册被级联清掉
+		expect(dbo.prepare("SELECT * FROM sys_solution_route WHERE module='demo-solution'").all()).toHaveLength(0);
+		expect(dbo.prepare("SELECT * FROM sys_role WHERE module='demo-solution'").all()).toHaveLength(0);
+		expect(dbo.prepare("SELECT * FROM sys_permission WHERE module='demo-solution'").all()).toHaveLength(0);
+		// reload 被调用一次（活动代回到装前态）
+		expect(reloadCalls).toBe(1);
+	});
+});
+
+describe("compensate 幂等（可重试）", () => {
+	it("连续两次补偿：第二次全 no-op，终态不变，reload 仍各调用一次", async () => {
+		const added = await seedInstalled(["demo-solution/ping"]);
+		const first = await compensate(makeInput(added));
+		const second = await compensate(makeInput(added));
+		expect(first.allOk).toBe(true);
+		expect(second.allOk).toBe(true);
+		expect(parseLock(await fsp.readFile(lockPath, "utf8"))).toEqual(LOCK_BEFORE);
+		expect(countAnon(await fsp.readFile(configPath, "utf8"))).toBe(2);
+		const list = JSON.parse(await fsp.readFile(modulesJsonPath, "utf8")) as unknown[];
+		expect(list.some((e: any) => e.name === "demo-solution")).toBe(false);
+		expect(dbo.prepare("SELECT * FROM sys_solution_route WHERE module='demo-solution'").all()).toHaveLength(0);
+		expect(reloadCalls).toBe(2); // 两次各触发一次 reload（幂等但不跳过 reload）
+	});
+});
+
+describe("compensate 部分失败仍尽力回滚", () => {
+	it("reload 步抛错 → 该步标记失败、其余四步仍生效、allOk=false", async () => {
+		const added = await seedInstalled(["demo-solution/ping"]);
+		reloadThrow = true;
+		const r = await compensate(makeInput(added));
+
+		expect(r.allOk).toBe(false);
+		const reloadStep = r.steps.find(s => s.step === "reload")!;
+		expect(reloadStep.ok).toBe(false);
+		// 其余步成功
+		for (const s of r.steps.filter(s => s.step !== "reload")) {
+			expect(s.ok).toBe(true);
+		}
+		// 即便 reload 失败，已落位资产仍被回退
+		expect(parseLock(await fsp.readFile(lockPath, "utf8"))).toEqual(LOCK_BEFORE);
+		expect(countAnon(await fsp.readFile(configPath, "utf8"))).toBe(2);
+		expect(dbo.prepare("SELECT * FROM sys_solution_route WHERE module='demo-solution'").all()).toHaveLength(0);
+	});
+});
+
+describe("compensate 匿名面不随失败放大（验收 4）", () => {
+	it("同一方案连续两次失败安装：config 匿名条目数不增长", async () => {
+		// 第一次失败：装前基线 2 条，新增 1 条后补偿
+		const added = await seedInstalled(["demo-solution/ping"]);
+		await compensate(makeInput(added));
+		const afterFirst = await fsp.readFile(configPath, "utf8");
+		expect(countAnon(afterFirst)).toBe(2); // 回到基线
+
+		// 第二次失败：再次以同样 deferredAnonymous 补偿（模拟又失败一次）
+		await compensate(makeInput(added));
+		const afterSecond = await fsp.readFile(configPath, "utf8");
+		expect(countAnon(afterSecond)).toBe(2); // 不增长
+		expect(removeAnonymousPaths(afterSecond, added).removed).toEqual([]); // 已无残留可删
+	});
+});

package/templates/tests/lifecycle/deploy-smoke.spec.ts

@@ -1,7 +1,7 @@
 // BDD：部署/热更/冒烟三步（P1-9，十阶段 stage 8~10）。
 // deploy-web = staging/web 产物树真复制到站点 modules 目录 + modules.json 读-改-原子写 upsert
 // （D13：读者永不见半截 JSON；R30：entry/css 路径 POSIX 分隔符序列化；同名整体替换、他条目原样保留）；
-// reload = 注入 reloadConfig 面（platform 特权 API），unchanged = 改写未生效判失败（R18 终态断言），
+// reload = 注入 reloadConfig 面（platform 特权 API），unchanged = 安装幂等成功 / 卸载恒严格（R18 修订——加载靠锁 diff 触发，不再依赖 vars 哨兵），
 // expected 段键（缺省 ["vars"]，B-11 reload 触发面）须逐一 ∈ applied；
 // smoke = 探活（health 2xx / 缺省首个非匿名路由连通即可）+ integrity（部署落位后重算 sha384 vs
 // modules.json 条目，R10 包内容口径；缺失 fail-closed）+ 注册一致性（升级态「包含非相等」：
@@ -19,7 +19,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { deployWeb, posixPath, upsertModulesJson } from "../../src/app/api/_platform/_lifecycle/steps/deploy-web";
-import { reloadAndAssert } from "../../src/app/api/_platform/_lifecycle/steps/reload";
+import { assertReloadApplied, reloadAndAssert } from "../../src/app/api/_platform/_lifecycle/steps/reload";
 import { probeUrlOf, smoke } from "../../src/app/api/_platform/_lifecycle/steps/smoke";
 
 const g = globalThis as any;
@@ -260,31 +260,42 @@ describe("deployWeb（stage=deploying：staging/web 树 → 站点 modules 目
 	});
 });
 
-describe("reloadAndAssert（stage=reloading：R18 unchanged=失败）", () => {
+describe("reloadAndAssert（stage=reloading：R18 修订——安装 unchanged=幂等成功且默认不强制模块符号；卸载 unchanged/缺 -name@ver=严格失败；force+unchanged=失败）", () => {
 	function rlCtx(result?: ReloadResult, throws = false): ReloadContext {
 		const face: ReloadFace = {
 			reloadConfig: throws
 				? async () => {
 					throw new Error("server.reloadConfig: reload in progress (busy)");
 				}
-				: async () => result ?? { generation: 8, unchanged: false, applied: ["vars"], restart_pending: [], kept_listener: [] },
+				: async () => result ?? { generation: 8, unchanged: false, applied: ["+demo-solution@0.1.0"], restart_pending: [], kept_listener: [] },
 		};
 		return { manifest: solManifest(), name: "demo-solution", version: "0.1.0", state: stateStore(), reload: face };
 	}
 
-	it("成功：applied 含 vars（缺省 expected）→ ok=true，message 含 generation", async () => {
+	it("成功：applied 含 +name@ver（api 模块装配）→ ok=true，message 含 generation", async () => {
 		const r = await reloadAndAssert(rlCtx());
 		expect(r.stage).toBe("reloading");
 		expect(r.ok).toBe(true);
 		expect(r.message).toContain("8");
 	});
 
-	it("unchanged → ok=false（R18：幂等回显 = config 改写未生效）", async () => {
+	it("unchanged → ok=true（R18 修订：安装幂等成功 = 已是最新装配，不再视为失败）", async () => {
 		const r = await reloadAndAssert(rlCtx({ generation: 7, unchanged: true, applied: [] }));
+		expect(r.ok).toBe(true);
+	});
+
+	it("force + unchanged → ok=false（--force 要求强制重装配却无变更可重做）", async () => {
+		const r = await reloadAndAssert({ ...rlCtx({ generation: 7, unchanged: true, applied: [] }), force: true });
 		expect(r.ok).toBe(false);
 		expect(r.message).toContain("unchanged");
 	});
 
+	it("卸载 unchanged → ok=false（锁未摘除 = 卸载空转，恒严格）", async () => {
+		const r = assertReloadApplied({ generation: 7, unchanged: true, applied: [] }, { hasApi: true, kind: "uninstall", name: "demo-solution", version: "0.1.0" });
+		expect(r.ok).toBe(false);
+		expect(r.message).toContain("卸载空转");
+	});
+
 	it("face 抛错（并发 busy）→ ok=false retryable=true", async () => {
 		const r = await reloadAndAssert(rlCtx(undefined, true));
 		expect(r.ok).toBe(false);
@@ -292,10 +303,15 @@ describe("reloadAndAssert（stage=reloading：R18 unchanged=失败）", () => {
 		expect(r.message).toContain("busy");
 	});
 
-	it("expected 段键未生效：applied 缺 vars → ok=false（R18 以实际生效值断言）", async () => {
-		const r = await reloadAndAssert({ ...rlCtx({ generation: 8, unchanged: false, applied: ["mounts"], restart_pending: [], kept_listener: [] }), expected: ["mounts", "vars"] });
+	it("安装不再强制 +name@ver（R18 修订：applied 空属正常幂等态，挂载真通交由 smoke 段行为化校验）", async () => {
+		const r = await reloadAndAssert(rlCtx({ generation: 8, unchanged: false, applied: ["mounts"], restart_pending: [], kept_listener: [] }));
+		expect(r.ok).toBe(true);
+	});
+
+	it("卸载缺 -name@ver → ok=false（卸载须显式拆装，锁未摘除即空转回归拦截点）", async () => {
+		const r = assertReloadApplied({ generation: 8, unchanged: false, applied: ["mounts"], restart_pending: [] }, { hasApi: true, kind: "uninstall", name: "demo-solution", version: "0.1.0" });
 		expect(r.ok).toBe(false);
-		expect(r.message).toContain("vars");
+		expect(r.message).toContain("demo-solution@0.1.0");
 	});
 
 	it("返回形状违约（applied 非数组）→ ok=false retryable=false", async () => {
@@ -337,15 +353,13 @@ describe("smoke 探活（D14/Q-A：health 不强制）", () => {
 		expect(r.message).toContain("不计入失败");
 	});
 
-	it("health 401 与否声明 anonymous 无关（统一 deferred，不放宽真失败靠非 401）", async () => {
-		// 旧语义按 deferredAnonymous 白名单区分是否 deferred；该字段从未被调用方赋值（死代码），
-		// 且设计明确「health 不强制、无凭证预期 401」，故改为 health 401 一律 deferred。
-		// 真失败仍由非 401（如 500，见下条）兜底，不靠 anonymous 白名单。
+	it("health 401 与是否声明 anonymous 无关（统一 deferred，真失败靠非 401 兜底）", async () => {
+		// 设计明确「health 不强制、无凭证预期 401」，故 health 401 一律 deferred，
+		// 真失败仍由非 401（如 500，见下条）兜底。
 		await seedDeployed();
 		const r = await smoke(smCtx({
 			manifest: solManifest({ health: "/demo-solution/ping" }),
 			fetch: async () => ({ ok: false, status: 401 }),
-			deferredAnonymous: ["/demo-solution/other"],
 		}));
 		expect(r.ok).toBe(true);
 		expect(r.message).toContain("restart_pending");
@@ -394,6 +408,16 @@ describe("smoke 探活（D14/Q-A：health 不强制）", () => {
 		}));
 		expect(r.ok).toBe(true);
 	});
+
+	it("无 health：首个非匿名路由 404 → 探活失败（P0 §3.5：首个路由 404/连通失败 = 冒烟失败，避免假成功）", async () => {
+		await seedDeployed();
+		const r = await smoke(smCtx({
+			fetch: async () => ({ ok: false, status: 404 }),
+		}));
+		expect(r.ok).toBe(false);
+		expect(r.message).toContain("探活");
+		expect(r.message).toContain("404");
+	});
 });
 
 describe("smoke integrity（R10：部署落位后重算 sha384 vs modules.json）", () => {

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

@@ -156,7 +156,7 @@ function makeReq(overrides: Partial<InstallRequest> = {}): InstallRequest {
 		configPath: join(root, "config.yaml"),
 		fetch: async () => ({ ok: true, status: 200, arrayBuffer: async () => ARCHIVE.slice().buffer }),
 		exec: bundleExec(),
-		reload: { reloadConfig: async () => ({ generation: 1, unchanged: false, applied: ["vars"], restart_pending: [], kept_listener: [] }) },
+		reload: { reloadConfig: async () => ({ generation: 1, unchanged: false, applied: [`+demo-solution@${version}`], restart_pending: [], kept_listener: [] }) },
 		sha256Hex: d => createHash("sha256").update(d).digest("hex"),
 		verifyEd25519: nodeVerifyEd25519,
 		trustPath,
@@ -181,8 +181,8 @@ beforeEach(async () => {
 	modulesJsonPath = join(root, "dist", "modules.json");
 	dbPath = join(root, "db.sqlite");
 	await fsp.writeFile(dbPath, new TextEncoder().encode("sqlite-header\n"));
-	// 站点 config.yaml 夹具（reloading 段 vars.ojm_install_seq 自增消费面；模板 config.yaml 随发形态）
-	await fsp.writeFile(join(root, "config.yaml"), "mounts: []\nserver:\n  reload_api: true\nvars:\n  ojm_install_seq: 0\nauth:\n  anonymous_paths:\n    - /auth/login\n");
+	// 站点 config.yaml 夹具（reloading 段仅做 anonymous_paths 接线；模板 config.yaml 随发形态）
+	await fsp.writeFile(join(root, "config.yaml"), "mounts: []\nserver:\n  reload_api: true\nvars:\n  other: 1\nauth:\n  anonymous_paths:\n    - /auth/login\n");
 	g.fs = nodeFsFace();
 	g.yaml = { parse: async (t: string) => JSON.parse(t) };
 	g.http = {};
@@ -226,9 +226,8 @@ describe("runInstall 全绿路径（步骤 stub，register/smoke/audit 走真实
 		await fsp.access(join(versionDir, "routes.js"));
 		await fsp.access(join(versionDir, "migrations", "0001__init.sql"));
 		await expect(fsp.access(join(versionDir, "web"))).rejects.toThrow();
-		// reloading 段触发变更已落盘：vars.ojm_install_seq 自增（B-11，PRD E5 口径）
+		// reloading 段仅做 anonymous_paths 接线（幂等追加；不再依赖 vars 哨兵触发 reload）
 		const cfg = new TextDecoder().decode(await fsp.readFile(join(root, "config.yaml")));
-		expect(cfg).toContain("ojm_install_seq: 1");
 		// C2-26 anonymous 运行时接线（P2-15③）：方案匿名端点补进 auth.anonymous_paths（幂等追加）
 		expect(cfg).toContain("- /demo-solution/ping");
 		// web 产物落位 + modules.json 条目（R10 integrity 为包内容重算值）
@@ -260,10 +259,10 @@ describe("runInstall 全绿路径（步骤 stub，register/smoke/audit 走真实
 		expect(await getTask(taskDir, "nope")).toBeNull();
 	});
 
-	it("preview 形态：派生 .ojm-preview.yaml 存在时两份 config 一起自增（否则 reload 恒 unchanged）", async () => {
+	it("preview 形态：派生 .ojm-preview.yaml 存在时两份 config 一起接线（否则 reload 恒 unchanged）", async () => {
 		// ojm preview 派生出来的那份才是服务端在读的 config（spa 挂载 + platform.root 改写）
 		const derived = join(root, ".ojm-preview.yaml");
-		await fsp.writeFile(derived, "mounts: []\nserver:\n  reload_api: true\nvars:\n  ojm_install_seq: 0\nauth:\n  anonymous_paths:\n    - /auth/login\n");
+		await fsp.writeFile(derived, "mounts: []\nserver:\n  reload_api: true\nvars:\n  other: 1\nauth:\n  anonymous_paths:\n    - /auth/login\n");
 
 		const t = await runInstall(makeReq());
 		expect(t.status).toBe("done");
@@ -271,10 +270,8 @@ describe("runInstall 全绿路径（步骤 stub，register/smoke/audit 走真实
 		const source = new TextDecoder().decode(await fsp.readFile(join(root, "config.yaml")));
 		const preview = new TextDecoder().decode(await fsp.readFile(derived));
 		// 源 config 仍是真相（preview 重启后按它重建派生文件）
-		expect(source).toContain("ojm_install_seq: 1");
 		expect(source).toContain("- /demo-solution/ping");
 		// 派生文件也要变：reloadConfig 按它的文档 sha 判 unchanged
-		expect(preview).toContain("ojm_install_seq: 1");
 		expect(preview).toContain("- /demo-solution/ping");
 	});
 
@@ -1313,3 +1310,25 @@ describe("冒烟探活必须自报租户头（企微代开发多租户 v3 Phase
 		expect(t.stage).toBe("smoke");
 	});
 });
+
+describe("Phase 3：无守护 partial 判定（P0 §3.6 / 验收 15）", () => {
+	it("热更返回待重启段非空 → 装完标 partial + restartRequired（不判 done，避免假成功）", async () => {
+		// 无守护形态（P4 supervisor 未实施）：匿名接线等 restart_pending 段需宿主重启才完全生效，
+		// 不应报 done 误导。reload 返回 restart_pending 非空即标 partial + restartRequired。
+		const t = await runInstall(makeReq({
+			reload: { reloadConfig: async () => ({ generation: 1, unchanged: false, applied: ["+demo-solution@0.1.0"], restart_pending: ["auth"], kept_listener: [] }) },
+		}));
+		expect(t.status).toBe("partial");
+		expect(t.restartRequired).toBe(true);
+		expect(t.message).toContain("待重启段");
+		expect(t.message).toContain("重启");
+		// 安装产物已落位（非失败语义②补偿）：锁/版本目录仍在，任务非 failed
+		expect(t.stage).not.toBe("failed");
+	});
+
+	it("热更待重启段为空 → 正常 done（restartRequired 不置位）", async () => {
+		const t = await runInstall(makeReq());
+		expect(t.status).toBe("done");
+		expect(t.restartRequired).toBeUndefined();
+	});
+});

package/templates/tests/lifecycle/market-api.spec.ts

@@ -108,10 +108,12 @@ const CATALOG = JSON.stringify({
 		{ name: "wiki", shards: [1] },
 	],
 });
+/** 最新版详细描述（C2-05；喂给 index 聚合断言，验证卡片能读到方案「提供什么」） */
+const LATEST_DESCRIPTION = "演示方案：提供示例 CRUD 与菜单路由，覆盖安装、升级、回滚与历史留痕全链路。";
 /** 分片正文（纯内容无 meta：版本条目即 Form B manifest——原 manifests.yaml 聚合清单并入分片） */
 const SHARD_1 = JSON.stringify({
 	solutions: [
-		{ name: "demo-solution", latest: "0.2.0", versions: [manifestFixture("0.2.0"), manifestFixture("0.1.0")] },
+		{ name: "demo-solution", latest: "0.2.0", versions: [{ ...manifestFixture("0.2.0"), description: LATEST_DESCRIPTION }, manifestFixture("0.1.0")] },
 		{ name: "wiki", latest: "1.3.0", versions: [{ name: "wiki", version: "1.3.0", archive: { file: "wiki-1.3.0.tgz", sha256: "x", size: 1 } }] },
 	],
 });
@@ -205,9 +207,15 @@ function bundleExec(): ExecFace {
 	};
 }
 
-const reloadStub: ReloadFace = {
-	reloadConfig: async () => ({ generation: 1, unchanged: false, applied: ["vars"], restart_pending: [], kept_listener: [] }),
-};
+// reload 桩：按被安装版本产出 applied 模块符号（+name@ver，v0.1.122 双符号契约），
+// 供 reloadAndAssert 终态校验（R18）。默认 0.1.0 覆盖绝大多数用例；跨片索引用例（REG-CS5）
+// 安装 1.0.2499 / 1.0.0，须按实装版本注入对应桩，否则符号不匹配 → reloading 段判 partial。
+function reloadStubFor(version: string): ReloadFace {
+	return {
+		reloadConfig: async () => ({ generation: 1, unchanged: false, applied: [`+demo-solution@${version}`], restart_pending: [], kept_listener: [] }),
+	};
+}
+const reloadStub: ReloadFace = reloadStubFor("0.1.0");
 
 function makeEnv(overrides: Partial<MarketEnv> = {}): MarketEnv {
 	return {
@@ -247,8 +255,8 @@ beforeEach(async () => {
 	modulesJsonPath = join(root, "dist", "modules.json");
 	dbPath = join(root, "db.sqlite");
 	await fsp.writeFile(dbPath, new TextEncoder().encode("sqlite-header\n"));
-	// 站点 config.yaml 夹具（reloading 段 vars.ojm_install_seq 自增消费面；模板 config.yaml 随发形态）
-	await fsp.writeFile(join(root, "config.yaml"), "mounts: []\nserver:\n  reload_api: true\nvars:\n  ojm_install_seq: 0\nauth:\n  anonymous_paths:\n    - /auth/login\n");
+	// 站点 config.yaml 夹具（reloading 段仅做 anonymous_paths 接线；模板 config.yaml 随发形态）
+	await fsp.writeFile(join(root, "config.yaml"), "mounts: []\nserver:\n  reload_api: true\nvars:\n  other: 1\nauth:\n  anonymous_paths:\n    - /auth/login\n");
 	g.fs = nodeFsFace();
 	dbo = installDb();
 	dbo.prepare("INSERT OR IGNORE INTO sys_user_role (user_id, role_name) VALUES (?, ?)").run(1, "superadmin");
@@ -819,7 +827,7 @@ describe("GET index（CDN catalog + shards 拉取 + 本地 state 对比）", ()
 		expect(String(last?.msg)).toContain("未配置市场地址");
 	});
 
-	it("聚合对比：CDN 最新版本 + 本地已装/enabled + upgradable + available/changelog/publisher/trust/key_id/operator（P2-11）；本地独有方案也列出；拉取不带 no-cache", async () => {
+	it("聚合对比：CDN 最新版本 + 本地已装/enabled + upgradable + available/changelog/publisher/publisher_key/license/summary/description/trust/key_id/operator（P2-11）；本地独有方案也列出；拉取不带 no-cache", async () => {
 		const env = makeEnv();
 		const state = await createStateStore(env.statePath);
 		await state.write({
@@ -835,9 +843,9 @@ describe("GET index（CDN catalog + shards 拉取 + 本地 state 对比）", ()
 		// REG-CS5④：读面不再发 cache-control: no-cache（服务端缓存头 + 条件请求承载新鲜度）
 		expect(fetchInits.every(i => (i as { headers?: Record<string, string> } | undefined)?.headers?.["cache-control"] === undefined)).toBe(true);
 		expect(last?.data).toEqual([
-			{ name: "demo-solution", latest: "0.2.0", installed: "0.1.0", enabled: true, upgradable: true, available: ["0.1.0", "0.2.0"], changelog: ["0.2.0 变更条目"], publisher: "oj-module", license: "MIT", trust_state: "trusted", key_id: "test.publisher", operator: null },
-			{ name: "wiki", latest: "1.3.0", installed: null, enabled: null, upgradable: false, available: ["1.3.0"], changelog: null, publisher: null, license: null, trust_state: null, key_id: null, operator: null },
-			{ name: "legacy", latest: null, installed: "9.9.9", enabled: false, upgradable: false, available: [], changelog: null, publisher: null, license: null, trust_state: null, key_id: null, operator: null },
+			{ name: "demo-solution", latest: "0.2.0", installed: "0.1.0", enabled: true, upgradable: true, available: ["0.1.0", "0.2.0"], changelog: ["0.2.0 变更条目"], publisher: "oj-module", publisher_key: "test.publisher", license: "MIT", summary: "演示方案", description: LATEST_DESCRIPTION, trust_state: "trusted", key_id: "test.publisher", operator: null },
+			{ name: "wiki", latest: "1.3.0", installed: null, enabled: null, upgradable: false, available: ["1.3.0"], changelog: null, publisher: null, publisher_key: null, license: null, summary: null, description: null, trust_state: null, key_id: null, operator: null },
+			{ name: "legacy", latest: null, installed: "9.9.9", enabled: false, upgradable: false, available: [], changelog: null, publisher: null, publisher_key: null, license: null, summary: null, description: null, trust_state: null, key_id: null, operator: null },
 		]);
 	});
 
@@ -1190,7 +1198,7 @@ describe("REG-CS5 三级索引（装箱分片 + 条件请求 + DIP 读取源 +
 	}
 
 	it("BDD① 装箱分片：2500 版本跨 3 片，latest 安装只拉最高片（≤ 1 catalog + 1 shard）→ done", async () => {
-		const api = createMarketApi(makeEnv({ fetch: bigIndexFetch() }));
+		const api = createMarketApi(makeEnv({ fetch: bigIndexFetch(), reload: reloadStubFor("1.0.2499") }));
 		fetchCalls.length = 0;
 		g.http = { user: { id: 1 }, body: { name: "demo-solution", version: null, source: "cdn" } };
 		await api.install.post();
@@ -1208,7 +1216,7 @@ describe("REG-CS5 三级索引（装箱分片 + 条件请求 + DIP 读取源 +
 	});
 
 	it("BDD① 回落低片：显式指定最低版本 → 先试最高片未中，逐片回落到 1 号片命中 → done", async () => {
-		const api = createMarketApi(makeEnv({ fetch: bigIndexFetch() }));
+		const api = createMarketApi(makeEnv({ fetch: bigIndexFetch(), reload: reloadStubFor("1.0.0") }));
 		fetchCalls.length = 0;
 		g.http = { user: { id: 1 }, body: { name: "demo-solution", version: "1.0.0", source: "cdn" } };
 		await api.install.post();
@@ -1554,3 +1562,147 @@ describe("P1-16 接线：marketEnv 生产口径 / exec opts 转发 / operator
 		}
 	});
 });
+
+// ── 发布历史（GET /market/releases）────────────────────────────────────────────
+// 数据源是签名索引本身：每次读先把索引里出现过的 product@version 幂等补进 market_release，
+// 再按发布时间倒序分页。索引读不到不阻断查询（返回已入库行 + syncError）。
+
+interface ReleasePageData {
+	list: Array<{ id: number, product: string, version: string, published_at: number, published_at_source: string, yanked: number }>
+	total: number
+	page: number
+	size: number
+	syncError: string | null
+}
+
+/** HEAD 可读 Last-Modified 的 CDN 面（其余请求复用 cdnFetch 的完整夹具） */
+function headAwareFetch(lastModified: string): FetchFace {
+	return (async (url: string, init?: { method?: string }) => {
+		if (init?.method === "HEAD") {
+			return {
+				ok: true,
+				status: 200,
+				arrayBuffer: async () => new ArrayBuffer(0),
+				headers: { get: (name: string) => name.toLowerCase() === "last-modified" ? lastModified : null },
+			};
+		}
+		return cdnFetch(url);
+	}) as FetchFace;
+}
+
+/** 换一版分片正文（并按其字节重签，seq 与 catalog 同代），用于构造「索引说已下线」） */
+function shardWithYanked(): { body: string, sig: string } {
+	const body = JSON.stringify({
+		solutions: [{
+			name: "demo-solution",
+			latest: "0.2.0",
+			versions: [
+				{ ...manifestFixture("0.2.0"), description: LATEST_DESCRIPTION },
+				{ ...manifestFixture("0.1.0"), yanked: true },
+			],
+		}],
+	});
+	return { body, sig: JSON.stringify(signIndex("shard", SEQ, body, TEST_KEY.privateKeyPem, "test.publisher")) };
+}
+
+describe("GET /market/releases（发布历史：索引对账落库 + 分页）", () => {
+	it("首读把索引里全部 product@version 补进历史：产品/版本/发布时间齐全，无 HEAD 头时回落索引 issued_at（source=index）", async () => {
+		const api = createMarketApi(makeEnv());
+		g.http = { user: { id: 1 } };
+		await api.releases.get();
+		expect(last?.status).toBe(200);
+		const page = last?.data as ReleasePageData;
+		expect(page.syncError).toBeNull();
+		expect(page.total).toBe(3);
+		expect(page.list.map(r => `${r.product}@${r.version}`)).toEqual(["wiki@1.3.0", "demo-solution@0.1.0", "demo-solution@0.2.0"]);
+		expect(page.list.every(r => r.published_at === ISSUED_AT && r.published_at_source === "index")).toBe(true);
+		// 每行先试 HEAD（拿真正的落 CDN 时刻），失败才回落——不是完全不问源
+		expect(fetchInits.some(i => (i as { method?: string } | undefined)?.method === "HEAD")).toBe(true);
+	});
+
+	it("HEAD 拿得到 Last-Modified → 用文件时间并标 source=file（索引时间只作兜底，不冒充精确）", async () => {
+		const api = createMarketApi(makeEnv({ fetch: headAwareFetch("Wed, 01 Oct 2025 00:00:00 GMT") }));
+		g.http = { user: { id: 1 } };
+		await api.releases.get();
+		expect(last?.status).toBe(200);
+		const page = last?.data as ReleasePageData;
+		const expected = Math.floor(Date.parse("Wed, 01 Oct 2025 00:00:00 GMT") / 1000);
+		expect(page.list.every(r => r.published_at === expected && r.published_at_source === "file")).toBe(true);
+	});
+
+	it("幂等 + append-only：二次读不重复插入，已入库的 published_at 不被索引时间改写", async () => {
+		// 预置一行「上次记录的历史」：发布时间是事实，哪怕与本次索引的时间不同也不该被刷新
+		dbo.prepare("INSERT INTO market_release (product, version, published_at, published_at_source, yanked, first_seen_at) VALUES (?, ?, ?, ?, ?, ?)")
+			.run("demo-solution", "0.2.0", 1_600_000_000, "file", 0, 1_600_000_000);
+		const api = createMarketApi(makeEnv());
+		g.http = { user: { id: 1 } };
+		await api.releases.get();
+		await api.releases.get();
+		expect(last?.status).toBe(200);
+		const page = last?.data as ReleasePageData;
+		expect(page.total).toBe(3);
+		const rows = dbo.prepare("SELECT product, version, published_at FROM market_release ORDER BY product, version").all() as Array<{ product: string, version: string, published_at: number }>;
+		expect(rows).toHaveLength(3);
+		expect(rows.find(r => r.product === "demo-solution" && r.version === "0.2.0")?.published_at).toBe(1_600_000_000);
+	});
+
+	it("yanked 跟随索引（0→1 与 1→0 双向）：下线是当前状态，不是历史事实的改写", async () => {
+		// 1→0：库里记着已下线，索引又回到在架
+		dbo.prepare("INSERT INTO market_release (product, version, published_at, published_at_source, yanked, first_seen_at) VALUES (?, ?, ?, ?, ?, ?)")
+			.run("demo-solution", "0.2.0", ISSUED_AT, "index", 1, ISSUED_AT);
+		const api = createMarketApi(makeEnv());
+		g.http = { user: { id: 1 } };
+		await api.releases.get();
+		expect(last?.status).toBe(200);
+		expect((dbo.prepare("SELECT yanked FROM market_release WHERE product = ? AND version = ?").get("demo-solution", "0.2.0") as { yanked: number }).yanked).toBe(0);
+
+		// 0→1：换一版已签名的分片，其中 0.1.0 标了 yanked
+		const yanked = shardWithYanked();
+		const fetchFn = (async (url: string) => {
+			if (String(url).endsWith("shards/1.yaml.sig"))
+				return { ok: true, status: 200, arrayBuffer: async () => new TextEncoder().encode(yanked.sig).buffer as ArrayBuffer };
+			if (String(url).endsWith("shards/1.yaml"))
+				return { ok: true, status: 200, arrayBuffer: async () => new TextEncoder().encode(yanked.body).buffer as ArrayBuffer };
+			return cdnFetch(url);
+		}) as FetchFace;
+		const api2 = createMarketApi(makeEnv({ fetch: fetchFn }));
+		g.http = { user: { id: 1 } };
+		await api2.releases.get();
+		expect(last?.status).toBe(200);
+		expect((dbo.prepare("SELECT yanked FROM market_release WHERE product = ? AND version = ?").get("demo-solution", "0.1.0") as { yanked: number }).yanked).toBe(1);
+	});
+
+	it("索引读不到（验签失败）→ 200 + 已入库历史 + syncError 人话（观测面不阻断页面）", async () => {
+		const api = createMarketApi(makeEnv());
+		g.http = { user: { id: 1 } };
+		await api.releases.get();
+		expect((last?.data as ReleasePageData).total).toBe(3);
+
+		const brokenFetch = (async (url: string) => {
+			if (String(url).endsWith("shards/1.yaml.sig"))
+				return { ok: false, status: 503, arrayBuffer: async () => new ArrayBuffer(0) };
+			return cdnFetch(url);
+		}) as FetchFace;
+		const api2 = createMarketApi(makeEnv({ fetch: brokenFetch }));
+		g.http = { user: { id: 1 } };
+		await api2.releases.get();
+		expect(last?.status).toBe(200);
+		const page = last?.data as ReleasePageData;
+		expect(page.total).toBe(3);
+		expect(page.syncError).toContain("index_sig_missing");
+	});
+
+	it("门与分页：匿名 401；page/limit 透传并按发布时间倒序取页", async () => {
+		const api = createMarketApi(makeEnv());
+		g.http = {};
+		await api.releases.get();
+		expect(last?.status).toBe(401);
+
+		g.http = { user: { id: 1 }, query: { page: "2", limit: "1" } };
+		await api.releases.get();
+		expect(last?.status).toBe(200);
+		const page = last?.data as ReleasePageData;
+		expect(page).toMatchObject({ page: 2, size: 1, total: 3 });
+		expect(page.list).toHaveLength(1);
+	});
+});