@oj-module/cli 0.2.66 → 0.2.68

package/templates/src/app/api/_platform/_lifecycle/compensate.ts

@@ -0,0 +1,136 @@
+// 安装补偿清单（P0 §3.5）：锁后失败（registering/deploying_web/reloading/smoke）时，把站点恢复到
+// 「装前代」状态——旧代继续服务，任务标 partial + 可重试。本模块是回滚的唯一入口（SRP：只负责
+// 逆序回滚已落盘资产，不含装前校验/审计/终态文案），各资产回滚原语各自单一函数（OCP：新增资产
+// 类型只需加一个原语 + 在此注册一步）。所有原语幂等（缺则 no-op），故补偿可安全被重试端点反复调用。
+// 与 cancelCleanup 的区别（intentionally 不同）：取消 = 回到装前且删版本目录；补偿 = 回到装前代
+// 但**保留版本目录**供重试。两者共用 revertLock（lock.ts）不重复锁回退逻辑（DRY）。
+
+import type { ReloadFace } from "./steps/reload";
+import { atomicWriteText, fsFace, isMissingPath } from "./atomic";
+import { revertLock } from "./lock";
+import { removeModulesJsonEntry } from "./steps/deploy-web";
+import { removeAnonymousPaths } from "./text-edit";
+import { revertRegistrations } from "./uninstall";
+
+/** 本仓 preview 派生文件名（与 cli preview-config.ts / installer.ts 逐字一致） */
+const PREVIEW_CONFIG_NAME = ".ojm-preview.yaml";
+
+/** 与 config 同目录的 preview 派生路径（无目录分隔符 = 同目录裸名）；本地化避免与 installer.ts 循环依赖 */
+function previewSiblingOf(configPath: string): string {
+	const cut = Math.max(configPath.lastIndexOf("/"), configPath.lastIndexOf("\\"));
+	return cut < 0 ? PREVIEW_CONFIG_NAME : `${configPath.slice(0, cut + 1)}${PREVIEW_CONFIG_NAME}`;
+}
+
+function isObj(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+export interface CompensateInput {
+	/** 方案名 */
+	name: string
+	/** 本次安装版本 */
+	version: string
+	/** config.yaml 路径（缺省 "config.yaml"） */
+	configPath: string
+	/** reloading 段真正新增的匿名路径（installer 已写入 req.deferredAnonymous）；空 = 未接线，config 步 no-op */
+	deferredAnonymous: string[]
+	/** 站点 sharedRoot（锁/版本目录所在） */
+	sharedRoot: string
+	/** 站点 modules.json 路径 */
+	modulesJsonPath: string
+	/** runInstall 起始捕获的装前锁快照 */
+	lockBefore: Record<string, string>
+	/** 装前锁文件是否存在（首装 = false → 回退即删锁） */
+	lockExisted: boolean
+	/** 注入式 reload 面（与 reloadStage 同源） */
+	reload: ReloadFace
+}
+
+export interface CompensateStep {
+	step: string
+	ok: boolean
+	message: string
+}
+
+export interface CompensateResult {
+	/** 各步结果（逆序：config → lock → modules.json → db → reload） */
+	steps: CompensateStep[]
+	/** 是否全部成功（任一步失败即 false，但其余步仍尽力执行） */
+	allOk: boolean
+}
+
+/**
+ * 执行补偿回滚。每步独立 try/catch：单步失败记录进 steps 并继续其余步，最终 allOk 反映整体；
+ * 调用方据 allOk 决定 task 文案（失败步需在 message 中点名，便于运维定位）。
+ */
+export async function compensate(input: CompensateInput): Promise<CompensateResult> {
+	const steps: CompensateStep[] = [];
+	const run = async (step: string, fn: () => Promise<void>): Promise<void> => {
+		try {
+			await fn();
+			steps.push({ step, ok: true, message: `${step}：已回滚到装前代` });
+		}
+		catch (e) {
+			steps.push({ step, ok: false, message: `${step}回滚失败：${String(e)}` });
+		}
+	};
+
+	const f = fsFace();
+
+	// 1. config 匿名移除（源 config + preview 派生，派生缺失即跳过）
+	await run("config.anonymous", async () => {
+		if (input.deferredAnonymous.length === 0) {
+			return;
+		}
+		for (const p of [input.configPath, previewSiblingOf(input.configPath)]) {
+			let content: string;
+			try {
+				content = new TextDecoder().decode(await f.readFile(p));
+			}
+			catch (e) {
+				if (isMissingPath(e)) {
+					continue;
+				}
+				throw e;
+			}
+			const { content: next, removed } = removeAnonymousPaths(content, input.deferredAnonymous);
+			if (removed.length > 0) {
+				await atomicWriteText(p, next);
+			}
+		}
+	});
+
+	// 2. lock 回写装前（首装则删锁；空锁拒启）
+	await run("lock", async () => {
+		await revertLock(input.sharedRoot, input.lockBefore, input.lockExisted);
+	});
+
+	// 3. modules.json 条目移除 + 断言（防并发写者插回）
+	await run("modules.json", async () => {
+		const { removed } = await removeModulesJsonEntry(input.name, { modulesJsonPath: input.modulesJsonPath });
+		if (!removed) {
+			return;
+		}
+		const list = JSON.parse(new TextDecoder().decode(await f.readFile(input.modulesJsonPath))) as unknown;
+		if (Array.isArray(list) && list.some(e => isObj(e) && e.name === input.name)) {
+			throw new Error("回滚后 modules.json 仍存在该模块条目（疑似并发写者插回）");
+		}
+	});
+
+	// 4. DB 注册回退（复用卸载事务：删 route + 级联清角色/权限）
+	await run("db.registrations", async () => {
+		await revertRegistrations(input.name);
+	});
+
+	// 5. reload 让旧代生效（best-effort 重同步活动代；抛错即记失败，目标=活动代回到装前态）
+	// 注：US-1 落地前上游仅按 config sha 判定——回退 config 会产出 applied（移除匿名），非 unchanged；
+	// US-1 落地后预期 unchanged===true。两种皆视为成功（只要未抛错）。
+	await run("reload", async () => {
+		const r = await input.reload.reloadConfig();
+		if (typeof r !== "object" || r === null || typeof r.unchanged !== "boolean") {
+			throw new Error("reloadConfig 返回形状违约（expected {unchanged:boolean,...}）");
+		}
+	});
+
+	return { steps, allOk: steps.every(s => s.ok) };
+}

package/templates/src/app/api/_platform/_lifecycle/installer.ts

@@ -24,8 +24,9 @@ import type { ReloadFace } from "./steps/reload";
 import type { InstallContext, InstallStage, StageResult, TaskRecord, TaskStatus } from "./types";
 import { auditOp } from "../_shared/service/infra/audit";
 import { atomicWriteText, fsFace, randomId } from "./atomic";
+import { compensate } from "./compensate";
 import { recordHistory } from "./history";
-import { acquireTaskLock, commitLockEntry, readLock, writeLock } from "./lock";
+import { acquireTaskLock, commitLockEntry, readLock, revertLock, writeLock } from "./lock";
 import { deployWeb } from "./steps/deploy-web";
 import { download } from "./steps/download";
 import { extract } from "./steps/extract";
@@ -36,7 +37,7 @@ import { reloadAndAssert } from "./steps/reload";
 import { smoke } from "./steps/smoke";
 import { verify } from "./steps/verify";
 import { getTask, readTasks, sweepTimedOut, writeTask } from "./tasks";
-import { appendAnonymousPaths, bumpInstallSeq } from "./text-edit";
+import { appendAnonymousPaths, readAnonymousPaths } from "./text-edit";
 import { createTrustStore } from "./trust";
 
 // db/http 为 oj isolate 注入全局（同模板 service 层惯例，register.ts/audit.ts 同款；测试由夹具装 globalThis.db）
@@ -66,7 +67,7 @@ export interface InstallRequest extends InstallContext {
 	modulesJsonPath: string
 	/** API 前缀（smoke 探针 URL 前缀，C2-13） */
 	apiPrefix: string
-	/** 站点 config.yaml 路径（reloading 段 vars.ojm_install_seq 自增落盘处；缺省 config.yaml） */
+	/** 站点 config.yaml 路径（reloading 段 anonymous_paths 接线落盘处；缺省 config.yaml） */
 	configPath?: string
 	/** 注入面（DIP）：下载 / exec（tar+oj）/ 热更 / sha384（R10 integrity 重算） */
 	fetch: FetchFace
@@ -301,11 +302,15 @@ export function declOf(req: InstallRequest): SolutionDecl {
 			title_key: typeof r.title_key === "string" ? r.title_key : undefined,
 			permissions: Array.isArray(r.permissions) ? r.permissions.map(String) : [],
 		})),
-		// 顶层 permissions[] 的 code：无角色权限点（系统预置点）唯一能落库的来源，别在此丢弃
+		// 顶层 permissions[] 透传 code + title_key（R2 展示锚随落库走，别在校验后丢弃）：
+		// 无角色权限点（系统预置点）唯一能落库的来源
 		permissions: (Array.isArray(m.permissions) ? m.permissions : [])
 			.filter(isObj)
-			.map(p => (typeof p.code === "string" ? p.code : ""))
-			.filter(Boolean),
+			.map(p => ({
+				code: typeof p.code === "string" ? p.code : "",
+				title_key: typeof p.title_key === "string" ? p.title_key : undefined,
+			}))
+			.filter(p => p.code !== ""),
 		settings,
 		routes: (Array.isArray(m.routes) ? m.routes : []).filter(isObj).map(r => ({
 			path: typeof r.path === "string" ? r.path : "",
@@ -352,7 +357,11 @@ function previewSiblingOf(configPath: string): string {
 	return cut < 0 ? PREVIEW_CONFIG_NAME : `${configPath.slice(0, cut + 1)}${PREVIEW_CONFIG_NAME}`;
 }
 
-/** 把「安装序号自增 + 匿名端点接线」写到一份 config 文本上；`optional` 用于派生文件不存在即跳过 */
+/**
+ * 把「匿名端点接线」写到一份 config 文本上；`optional` 用于派生文件不存在即跳过。
+ * 仅当匿名端点确有新增（added 非空）才落盘——无谓重写会改动 config 文档 sha，反而引发假阳性
+ * （reload unchanged 判定基于文档 sha + 锁 diff；盘上本就一致时什么都不写才是正确的幂等态）。
+ */
 async function patchConfigAt(configPath: string, anonymous: string[], optional = false): Promise<string[]> {
 	let content: string;
 	try {
@@ -363,17 +372,22 @@ async function patchConfigAt(configPath: string, anonymous: string[], optional =
 			return [];
 		throw e;
 	}
-	const bumped = bumpInstallSeq(content);
-	const patched = anonymous.length > 0 ? appendAnonymousPaths(bumped.content, anonymous) : { content: bumped.content, added: [] };
+	if (anonymous.length === 0)
+		return [];
+	const patched = appendAnonymousPaths(content, anonymous);
+	if (patched.added.length === 0)
+		return [];
 	await atomicWriteText(configPath, patched.content);
 	return patched.added;
 }
 
 /**
- * 热更段适配（B-11 reload 触发面）：先落盘触发变更再 reloadAndAssert——reloadConfig 的
- * unchanged 判定基于 config 文档 sha（oj-bin reload_bridge 真源），不落盘变更则热更恒
- * unchanged 必失败。触发变更 = vars.ojm_install_seq 自增（PRD E5 实测先例：vars 段语义值
- * 改动 applied 可热生效，无需改 mounts），经 text-edit 纯文本行操作（R18，注释/键序逐字保留）。
+ * 热更段适配（B-11 reload 触发面，R18 修订）：先落盘 anonymous_paths 接线再 reloadAndAssert。
+ * oj 0.1.122+ 的 `unchanged` 由 **manifests 锁 diff 自然触发**（安装/升级/降级即锁变化），
+ * 不再依赖 config 文档 sha（旧的 vars.ojm_install_seq 哨兵已删）；本段只做 anonymous_paths
+ * 接线（且幂等、仅 added 非空才落盘），其余变更（模块装配）由锁 diff 驱动，无需此处制造。
+ * 触发变更判定 = 文档 sha 或锁 diff 任一变化（oj-bin reload_bridge 真源）；盘上本就一致则
+ * `unchanged=true` = 已是最新装配 = 幂等成功（R18 修订：不再视为失败）。
  *
  * **preview 形态（`ojm preview`）**：服务端读的是同目录派生出来的 `.ojm-preview.yaml`（spa 挂载 +
  * platform.root 改写到 dist），安装器改的 `config.yaml` 它根本不看——于是 reload 按文档 sha 判
@@ -395,9 +409,12 @@ async function reloadStage(req: InstallRequest): Promise<StageResult> {
 		req.deferredAnonymous = added;
 	}
 	catch (e) {
-		return { stage: "reloading", ok: false, retryable: true, message: `热更失败：config.yaml 安装序号自增/匿名端点接线失败（${String(e)}）——reload unchanged 判定基于 config 文档 sha，无变更则热更不可能生效（B-11，PRD E5 口径）` };
+		return { stage: "reloading", ok: false, retryable: true, message: `热更失败：config.yaml 匿名端点接线失败（${String(e)}）——reload 由锁 diff / 文档 sha 变化触发，接线本身失败则热更无变更可落` };
 	}
-	return reloadAndAssert(req);
+	const rr = await reloadAndAssert(req);
+	// 捕获待重启段（P0 §3.6 / 验收 15）：非空 = 部分生效，installer 终态据其标 partial + restartRequired
+	req.restartPending = rr.restartPending;
+	return rr;
 }
 
 /** 终态审计（AC-P1-14）：done/partial 都落 oplog；自身失败仅日志（附录 B-5，不阻断任务终态） */
@@ -492,13 +509,7 @@ async function cancelCleanup(req: InstallRequest, lockBefore: Record<string, str
 		// staging 已不存在（首装取消 / 重复回退）不掩盖取消终态
 	}
 	try {
-		if (lockExisted) {
-			await writeLock(`${req.sharedRoot}/manifests.yaml`, lockBefore);
-		}
-		else {
-			// 首装：装前本无锁文件，取消后也不该留空锁（空锁拒启 S1-1.2）
-			await f.remove(`${req.sharedRoot}/manifests.yaml`, { force: true });
-		}
+		await revertLock(req.sharedRoot, lockBefore, lockExisted);
 	}
 	catch {
 		// 锁回退失败由 reconcile 对账兜底（D11）
@@ -570,6 +581,15 @@ export async function runInstall(req: InstallRequest): Promise<TaskRecord> {
 		catch {
 			lockExisted = false;
 		}
+		// P0 §3.2 质辩1 / E8：写锁前读 config 的 auth.anonymous_paths，注入 preflight 做残留检测
+		// （preflight 保持只读 ctx 的纯校验段纪律，不自己读盘）。config 缺失/解析失败 → 视为无残留。
+		try {
+			const cfg = new TextDecoder().decode(await fsFace().readFile(req.configPath ?? "config.yaml"));
+			req.existingAnonymousPaths = readAnonymousPaths(cfg);
+		}
+		catch {
+			req.existingAnonymousPaths = [];
+		}
 		// P2-13 段内进度：migrating 段 spawn 流式路径逐块触发；写链串行（回调 fire-and-forget
 		// 防交错），失败静默（进度观测面不阻断安装）
 		let progressChain: Promise<void> = Promise.resolve();
@@ -658,8 +678,27 @@ export async function runInstall(req: InstallRequest): Promise<TaskRecord> {
 					}
 				}
 				else {
-					// 失败语义②：锁后 partial——部分生效，不回滚已落位产物，给回滚指引 key
+				// 失败语义②：锁后 partial——执行补偿回滚到装前代（旧代继续服务、任务可重试），
+				// 不再「不回滚已落位产物」：消除失败放大匿名面/残留注册（final §0 缺陷之三）。
+				// 补偿各步独立 try/catch，单步失败仍尽力回滚其余步，结果进 task.stages 供运维定位。
+					const comp = await compensate({
+						name: req.name,
+						version: req.version,
+						configPath: req.configPath ?? "config.yaml",
+						deferredAnonymous: req.deferredAnonymous ?? [],
+						sharedRoot: req.sharedRoot,
+						modulesJsonPath: req.modulesJsonPath,
+						lockBefore,
+						lockExisted,
+						reload: req.reload,
+					});
+					for (const s of comp.steps) {
+						task.stages.push({ stage: `compensate.${s.step}`, ok: s.ok, message: s.message });
+					}
 					task.status = "partial";
+					if (!comp.allOk) {
+						task.message = `${r.message}；补偿回滚存在失败步（${comp.steps.filter(s => !s.ok).map(s => s.step).join("、")}），可重试`;
+					}
 				}
 				req.outcome = { ...req.outcome, status: task.status, failedStage: def.name };
 				break;
@@ -737,8 +776,22 @@ export async function runInstall(req: InstallRequest): Promise<TaskRecord> {
 			});
 		}
 		if (task.status === "done") {
-			task.stage = "done";
-			task.progress = 100;
+			// 无守护形态部分生效判定（P0 §3.6 / 验收 15）：热更返回的待重启段非空，且无 supervisor
+			// 自动换进程（P4 暂未实施）——安装产物已落位，但宿主须重启才完全生效（匿名接线/路由等
+			// restart_pending 段）。此时不判 done（避免「假成功」误导，final §0 缺陷之四），改标 partial
+			// + restartRequired，由 UI 展示重启提示。失败语义②的补偿不触发（本次安装成功，无需回滚）。
+			const pending = req.restartPending ?? [];
+			if (pending.length > 0) {
+				task.status = "partial";
+				task.restartRequired = true;
+				task.stage = "reloading";
+				req.outcome = { ...req.outcome, status: "partial", failedStage: "reloading" };
+				task.message = `安装已落位但需宿主重启才完全生效：待重启段 [${pending.join("、")}]（无守护形态无自动换进程；请重启 oj serve 后生效）。其余阶段均成功（partial，可重试以复检）`;
+			}
+			else {
+				task.stage = "done";
+				task.progress = 100;
+			}
 		}
 		task.finishedAt = Date.now();
 		await writeTask(req.taskDir, task);

package/templates/src/app/api/_platform/_lifecycle/lock.ts

@@ -93,6 +93,29 @@ export interface TaskLock {
 	release: () => Promise<void>
 }
 
+/**
+ * 回退锁到装前快照（D12 反向，与 setEnabled/cancelCleanup 同纪律）：装前存在 → 写回
+ * lockBefore；首装（装前无锁文件）→ 删锁文件（空锁拒启 S1-1.2）。失败上抛由调用方兜底
+ * （reconcile 对账 / 任务 partial）。cancelCleanup 与补偿清单共用此原语，避免两处各写一份锁回退。
+ */
+export async function revertLock(sharedRoot: string, lockBefore: Record<string, string>, lockExisted: boolean): Promise<void> {
+	const f = fsFace();
+	const lockPath = `${sharedRoot}/manifests.yaml`;
+	if (lockExisted) {
+		await writeLock(lockPath, lockBefore);
+	}
+	else {
+		try {
+			await f.remove(lockPath, { force: true });
+		}
+		catch (e) {
+			if (!isMissingPath(e)) {
+				throw e;
+			}
+		}
+	}
+}
+
 /** stale 阈值：与任务超时判 failed 同款 30min（R13/B9/R31 口径一致） */
 export const LOCK_STALE_MS = 30 * 60_000;
 

package/templates/src/app/api/_platform/_lifecycle/steps/deploy-web.ts

@@ -188,3 +188,31 @@ export async function deployWeb(ctx: DeployWebContext): Promise<StageResult> {
 		message: `部署完成：staging web/ → ${ctx.siteModulesDir}/，modules.json 已 upsert ${ctx.name}（entry ${entry.entry}${integrity ? `；integrity ${integrity}` : ""}；D13 原子写，读者永不见半截 JSON）`,
 	};
 }
+
+/**
+ * 移除 modules.json 中指定 name 的条目（P0 补偿清单 §3.5）：读→filter→原子写，与 upsert 同纪律
+ * （D13，原子写读者无感）；清单不存在 = 该模块从未入清单，视为已移除返回 removed=false；清单损坏
+ * 上抛 fail-closed。返回 removed 标志供补偿流程断言「写出后该 name 条目确已不存在」。
+ */
+export async function removeModulesJsonEntry(name: string, opts: { modulesJsonPath: string }): Promise<{ removed: boolean }> {
+	const f = fsFace();
+	let list: unknown;
+	try {
+		list = JSON.parse(new TextDecoder().decode(await f.readFile(opts.modulesJsonPath)));
+	}
+	catch (e) {
+		if (isMissingPath(e)) {
+			return { removed: false };
+		}
+		throw e;
+	}
+	if (!Array.isArray(list)) {
+		throw new TypeError("modules.json 顶层不是数组，拒绝修改（避免覆盖丢失既有条目）");
+	}
+	const next = list.filter(e => !(isObj(e) && e.name === name));
+	const removed = next.length !== list.length;
+	if (removed) {
+		await atomicWriteText(opts.modulesJsonPath, `${JSON.stringify(next, null, 2)}\n`);
+	}
+	return { removed };
+}

package/templates/src/app/api/_platform/_lifecycle/steps/preflight.ts

@@ -52,6 +52,9 @@ const RANGE_RE = /^(>=|<=|[><^=])?([0-9A-Z.-]+)$/i;
 /** C2-26①：anonymous 相对路径语法（无前导斜杠、无通配符；首字符 [a-z0-9] 使 _system/_platform 天然禁入） */
 const ANONYMOUS_RE = /^[a-z0-9][a-z0-9\-_.]*(?:\/[a-z0-9][a-z0-9\-_.]*)*$/;
 
+/** P0 §3.2 匿名保留段黑名单（显式拒装清单；与 C2-26 段内收敛互补——C2-26 挡「跨段」，本清单挡「保留段本身」） */
+const ANON_RESERVED_PREFIXES = ["_platform", "_system", "auth", "_lifecycle"];
+
 /** C2-17：路由 path 语法（首段首字符为字母；无参数段/通配符/尾斜杠） */
 const ROUTE_PATH_RE = /^\/[a-z][a-z0-9\-_]*(?:\/[a-z0-9\-_]+)*$/;
 
@@ -205,6 +208,18 @@ export async function preflight(ctx: InstallContext): Promise<StageResult> {
 		return e === undefined ? undefined : `${key}@${e.version}`;
 	};
 
+	// ── P0 §3.9 宿主能力门禁：模板声明所需 host 能力子集（manifest.requiresCapabilities），
+	// 宿主 ojInfo().capabilities 缺项即写锁前失败（零痕迹，不碰锁/库表/清单）。缺省 undefined 视为
+	// 宿主未上报 → fail-closed（能力缺失即拒）。既有模板不声明 → 门禁恒放行（不依赖上游 US-1 即先落地）。
+	const requires = Array.isArray(m.requiresCapabilities) ? m.requiresCapabilities as unknown[] : [];
+	if (requires.length > 0) {
+		const caps = ctx.capabilities ?? [];
+		const missing = requires.filter(c => typeof c === "string" && !caps.includes(c));
+		if (missing.length > 0) {
+			v.push({ clause: "C2-cap", code: "host_capability", detail: `宿主 oj 不支持本方案所需能力 ${JSON.stringify(missing)}（请升级 oj 至具备 ${JSON.stringify(requires)} 的版本后再装）` });
+		}
+	}
+
 	// ── C2-01 身份 name：白名单 + 保留名（§4.2，market 经 R9 恢复保留）──
 	if (typeof m.name !== "string" || !NAME_RE.test(m.name)) {
 		v.push({ clause: "C2-01", detail: `name「${String(m.name)}」不匹配 ^[a-z][a-z0-9-]{0,63}$（小写字母开头，仅小写字母/数字/连字符）` });
@@ -288,6 +303,8 @@ export async function preflight(ctx: InstallContext): Promise<StageResult> {
 	// ── api 段（C2-12/12a/12b/13/26）──
 	// C2-26② 段内收敛的「本方案段」：api.prefix 缺省 = name
 	let apiSeg = name;
+	// P0 §3.2 质辩1 / E8：本 manifest 声明的匿名条目集合（供下方 config 残留检测比对）
+	const declaredSet = new Set<string>();
 	const api = m.api;
 	if (api !== undefined) {
 		if (!isObj(api)) {
@@ -354,9 +371,13 @@ export async function preflight(ctx: InstallContext): Promise<StageResult> {
 							v.push({ clause: "C2-26", detail: `anonymous「${a}」不匹配相对路径语法 ^[a-z0-9][a-z0-9\\-_.]*(/[a-z0-9][a-z0-9\\-_.]*)*$（无前导斜杠/通配符；_system/_platform 段禁入）` });
 							continue;
 						}
+						declaredSet.add(a);
 						if (a.split("/")[0] !== apiSeg) {
 							v.push({ clause: "C2-26", detail: `anonymous「${a}」越段：首段必须 = 本方案段「${apiSeg}」（R8 段内收敛；_system/_platform 等保留段因此禁入）` });
 						}
+						if (ANON_RESERVED_PREFIXES.includes(a.split("/")[0] ?? "")) {
+							v.push({ clause: "C2-26", detail: `anonymous「${a}」指向保留段（${ANON_RESERVED_PREFIXES.join("/")}），禁用于匿名接线（P0 §3.2 黑名单）` });
+						}
 						if (LOGIN_ENDPOINT_RE.test(a)) {
 							v.push({ clause: "C2-26", detail: `anonymous「${a}」命中登录语义端点禁令（R8/S1 纵深防御：login/logout/token/session/signin/signup/auth）` });
 						}
@@ -370,6 +391,31 @@ export async function preflight(ctx: InstallContext): Promise<StageResult> {
 		}
 	}
 
+	// ── P0 §3.2 质辩1 / E8：config 残留匿名检测（写锁前拒装，避免同 prefix 换装静默继承）──
+	// 站点 config 已存在的 auth.anonymous_paths 中，凡落在目标 prefix（apiSeg）下却未被本次 manifest
+	// 声明的条目，一律拒装。运行期新增的匿名条目卸载即失效，仅「启动期已在 config 的残留」构成暴露面——
+	// 此处只挡安装入口，不挡已运行实例。真源 = ctx.existingAnonymousPaths（调用方写锁前读 config 注入；
+	// preflight 保持只读 ctx 的纯校验段纪律）。
+	// **保留段条目不在此查**：config 里 /auth/*、/_platform/* 等属宿主内建（如 /auth/login），方案永不
+	// 能注入（C2-26 段内收敛已挡住方案声明保留段匿名），故保留段 config 条目绝不会是方案残留——
+	// 纳入比对只会误伤宿主内建匿名端点（F4 假阳性）。
+	{
+		const existing = ctx.existingAnonymousPaths ?? [];
+		const residual: string[] = [];
+		// config 条目带前导斜杠（appendAnonymousPaths 统一补 /），归一去斜杠再取首段，
+		// 与 manifest 相对形态（无前导 /）保持一致比对口径。
+		const norm = (p: string) => p.replace(/^\//, "");
+		for (const e of existing) {
+			const seg = norm(e).split("/")[0] ?? "";
+			if (seg === apiSeg && !declaredSet.has(norm(e))) {
+				residual.push(e);
+			}
+		}
+		if (residual.length > 0) {
+			v.push({ clause: "C2-26", code: "anonymous_residual", detail: `config 已存在未被本次 manifest 声明的匿名条目（同 prefix 换装会静默继承）：${residual.join("、")}——请先清理 config.yaml 的 auth.anonymous_paths 后再安装` });
+		}
+	}
+
 	// ── web 段（C2-27 语法；integrity 重算比对属 deployWeb→smoke 段，不在本段）──
 	const web = m.web;
 	if (web !== undefined) {

package/templates/src/app/api/_platform/_lifecycle/steps/reload.ts

@@ -1,12 +1,17 @@
-// 热更步骤（P1-9，十阶段 stage reloading；R18）：经注入 reload 面调 oj server.reloadConfig()
-// （platform 特权 API，oj 0.1.75 起落地；S1-5.2 实测五键形状 {generation, unchanged, applied[],
-// restart_pending[], kept_listener[]}，与 POST /_system/config 同一 executor 同一把串行锁——
-// 并发第二次触发抛 busy 409）。终态断言（R18）：unchanged = config 改写未实际生效判失败
-// （幂等回显 = 热更目标未达成，重试不自愈）；expected 段键须逐一 ∈ applied——缺省 ["vars"]
-// （B-11 安装触发面 = vars.ojm_install_seq 自增，PRD E5 实测 vars 可热生效；S1-5 实测
-// anonymous_paths 热改属 restart_pending 不可热生效，mounts 断言可经 ctx.expected 覆盖）。
-// reload 面经 ctx 注入（DIP）：生产 = (globalThis as any).server.reloadConfig 包装（P1-10 接线），
-// 测试 stub 注入成功/unchanged/抛错三态。
+// 热更步骤（P1-9，十阶段 stage reloading）：经注入 reload 面调 oj server.reloadConfig()
+// （platform 特权 API，oj 0.1.75 起落地；v0.1.122 起 manifests 锁纳入变化检测——装/卸只动锁即
+// 触发装配，卸载空转由此解决）。返回形状恒定（api-manual §10）：
+//   { generation, unchanged, applied[], restart_pending[], kept_listener[] }
+// - applied 双符号契约（v0.1.122）：模块条目 `+<name>@<ver>`（装/升级）/ `-<name>@<ver>`（卸），
+//   段 diff 条目（mounts/tenant/tasks）同列一数组；升级 = `-旧@v` + `+新@v` 成对。
+// - unchanged=true 时三清单为空（config 与 manifests 锁双双未变）；v0.1.122 起 vars/auth 等
+//   冻结/特权段**如实归入 restart_pending**——旧版把 vars 静默误标进 applied 已修正。
+// 并发撞锁 → 抛 `reload in progress (busy)`（409）；归一/装配失败 → 抛 HTTP 400；交接中断 / cron
+// 拉起失败 → 抛 500（old task pool did not stop within 10s 等，新代任务就地收场）。
+// 终态断言（R18 修订 / §2.7）：安装路径 unchanged=true = 已是最新装配 = 幂等成功（不再判失败）；
+// 卸载 unchanged=true = 空转回归仍判失败。applied 符号：卸载强制 -name@ver；安装默认不强制
+// +name@ver（smoke 段行为化校验挂载是否真通——探活拿到 200 即证模块已装配）。force 透传
+// （v0.1.123）要求 reload 实际重跑（unchanged=false），否则判失败。reload 面经 ctx 注入（DIP）。
 
 import type { InstallContext } from "./preflight";
 
@@ -20,13 +25,17 @@ export interface ReloadResult {
 }
 
 export interface ReloadFace {
-	reloadConfig: () => Promise<ReloadResult>
+	/** oj 0.1.123+ 支持 reloadConfig(force)：force=true 强制重装配，绕过 unchanged 幂等短路 */
+	reloadConfig: (force?: boolean) => Promise<ReloadResult>
 }
 
 export interface ReloadContext extends InstallContext {
 	/** 注入式 reload 面（生产 = platform 特权 server.reloadConfig 包装；测试 stub） */
 	reload: ReloadFace
-	/** 须实际生效的段键（R18 终态断言）；缺省 ["vars"]（B-11 安装触发面） */
+	/**
+	 * 除模块符号外须逐一 ∈ applied 的附加段键（缺省空；v0.1.122 起 vars/auth 等冻结/特权段已归入
+	 *  restart_pending，不再入 applied——故不再默认期望 vars）
+	 */
 	expected?: string[]
 }
 
@@ -35,47 +44,102 @@ export interface StageResult {
 	ok: boolean
 	message: string
 	retryable?: boolean
+	/**
+	 * 热更返回的待重启段（v0.1.122 restart_pending）；非空 = 部分生效、需宿主重启后才完全生效。
+	 *  install/卸载形态均据其标 partial + restartRequired（无守护形态，P0 §3.6 / 验收 15）
+	 */
+	restartPending?: string[]
 }
 
-export async function reloadAndAssert(ctx: ReloadContext): Promise<StageResult> {
-	let r: ReloadResult;
-	try {
-		r = await ctx.reload.reloadConfig();
-	}
-	catch (e) {
-		return { stage: "reloading", ok: false, retryable: true, message: `热更失败：reloadConfig 抛错（${String(e)}）——并发 busy 可重试（附录 A reloading；R18）` };
-	}
+function isObj(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** 是否有 api 模块（决定 oj 是否产出装配条目）：web-only（无 api 段）不强制模块符号，仅校验 reload 已探测变更 */
+export function hasApiModule(manifest: unknown): boolean {
+	return isObj(manifest) && isObj(manifest.api);
+}
+
+/** 模块符号（v0.1.122 applied 双符号契约）：装 = +<name>@<ver>；卸 = -<name>@<ver> */
+export function moduleSymbolOf(name: string, version: string, kind: "install" | "uninstall"): string {
+	return `${kind === "install" ? "+" : "-"}${name}@${version}`;
+}
+
+/**
+ * reload 终态断言（R18 修订 / §2.7）：
+ * - 形状违约（非对象 / applied 非数组 / unchanged 非布尔）→ 失败。
+ * - unchanged=true（config 与 manifests 锁双双未变）：
+ *     · 卸载（kind=uninstall）→ 失败：锁未摘除 = 卸载空转回归（重试不自愈）。
+ *     · 安装 + force=true → 失败：--force 要求强制重装配，宿主却报告无变更可重做（装配径失效）。
+ *     · 安装 + 非强制 → **成功**：unchanged = 已是最新装配 = 幂等成功（R18 修订：不再视为失败；
+ *       升级/重装本就由 manifests 锁 diff 自然触发 unchanged=false，盘上本就一致时 idempotent ok）。
+ * - 模块符号（卸 -name@ver）：仅卸载且 hasApi 为真时强制——卸载必须显式拆装；安装**默认不强制**
+ *   +name@ver（R18 修订：smoke 段行为化校验挂载是否真通——探活端点 200 即证模块已装配，不必在
+ *   reload 层重复断言；锁 diff 自会驱动装配，applied 空属正常幂等态）。
+ * - 附加段键（ctx.expected，如 mounts/tenant/tasks）逐一 ∈ applied（覆盖项保留）。
+ * 返回 {ok, message?} 供调用方生成人话。
+ */
+export function assertReloadApplied(r: ReloadResult, opts: { hasApi: boolean, kind: "install" | "uninstall", name: string, version: string, additional?: string[], /** 强制热更（oj 0.1.123+ reloadConfig(force)）：unchanged 时须失败（强制装配未生效） */ force?: boolean }): { ok: boolean, message?: string } {
 	if (typeof r !== "object" || r === null || !Array.isArray(r.applied) || typeof r.unchanged !== "boolean") {
 		return {
-			stage: "reloading",
 			ok: false,
-			retryable: false,
-			message: `热更失败：reloadConfig 返回形状违约（S1-5.2 五键形状 {generation, unchanged, applied, restart_pending, kept_listener}）：${JSON.stringify(r)?.slice(0, 200)}`,
+			message: `reloadConfig 返回形状违约（v0.1.122 五键 {generation, unchanged, applied[], restart_pending[], kept_listener[]}）：${JSON.stringify(r)?.slice(0, 200)}`,
 		};
 	}
+	// 无代际信号（dev/embedded 的 reload 回落 no-op：不提供 generation）= 无法验证，放行（不阻挡
+	// 卸载/安装主流程；真实 reload 恒返回 generation，故此信号等价于「reload 未实际执行」）。
+	if (r.generation === undefined) {
+		return { ok: true };
+	}
 	if (r.unchanged) {
+		if (opts.kind === "uninstall") {
+			return {
+				ok: false,
+				message: "reloadConfig 返回 unchanged——卸载后锁未变化，疑似卸载空转（锁未摘除）；请确认宿主已开启 reload_api 且 oj ≥ v0.1.122",
+			};
+		}
+		if (opts.force === true) {
+			return {
+				ok: false,
+				message: "reloadConfig 返回 unchanged——--force 要求强制重装配，但宿主报告无变更可重做（锁 diff / 文档 sha 变化后仍 unchanged 说明强制装配未生效）；请确认宿主 oj ≥ v0.1.123 且 reload_api 已开启",
+			};
+		}
+		// 非强制安装：unchanged = 已是最新装配 = 幂等成功（R18 修订）
 		return {
-			stage: "reloading",
-			ok: false,
-			retryable: false,
-			message: "热更失败：reloadConfig 返回 unchanged——config 改写未实际生效（R18 终态断言：幂等回显 = 热更目标未达成，重试不自愈），请检查 config 写入段后重试安装",
+			ok: true,
+			message: "reloadConfig 返回 unchanged——当前已是最新装配（幂等成功，R18 修订：锁 / 文档未变化即无需重装配）",
 		};
 	}
-	// 安装路径缺省期望 vars（B-11：reload 触发变更 = vars.ojm_install_seq 自增，PRD E5 实测
-	// vars 可热生效；unchanged 判定基于 config 文档 sha，安装器 reloading 段前置落盘自增）。
-	// anonymous 并入即 mounts 段生效的语义保留——调用方经 ctx.expected 显式覆盖。
-	const expected = ctx.expected ?? ["vars"];
-	const missing = expected.filter(k => !r.applied.includes(k));
+	// 模块符号：仅卸载且 hasApi 为真时强制 -name@ver（R18 修订：安装默认不强制 +name@ver，
+	// 由 smoke 段行为化校验挂载；本层只拦卸载空转——锁未摘除 = 未实际拆除）。
+	const requireSymbol = opts.kind === "uninstall" && opts.hasApi;
+	const symbol = requireSymbol ? moduleSymbolOf(opts.name, opts.version, "uninstall") : undefined;
+	const missing = [...(symbol ? [symbol] : []), ...(opts.additional ?? [])].filter(k => !r.applied.includes(k));
 	if (missing.length > 0) {
 		return {
-			stage: "reloading",
 			ok: false,
-			retryable: false,
-			message: `热更失败：applied [${r.applied.join("、")}] 未含预期生效段 ${missing.join("、")}（R18：以 reload 返回的 mounts/vars 实际生效值做终态断言）`,
+			message: `reloadConfig applied [${r.applied.join("、")}] 未含预期生效项 ${missing.join("、")}（R18 / §2.7：以 reload 实际 applied 做终态断言，卸载空转回归的唯一拦截点）`,
 		};
 	}
+	return { ok: true };
+}
+
+export async function reloadAndAssert(ctx: ReloadContext): Promise<StageResult> {
+	let r: ReloadResult;
+	try {
+		r = await ctx.reload.reloadConfig(ctx.force === true ? ctx.force : undefined);
+	}
+	catch (e) {
+		return { stage: "reloading", ok: false, retryable: true, message: `热更失败：reloadConfig 抛错（${String(e)}）——并发 busy / 归一装配失败 / 交接中断 / cron 拉起失败均可重试（R18）` };
+	}
+	// 安装路径（R18 修订）：默认不强制 +name@ver——模块装配由锁 diff 驱动，smoke 段行为化校验挂载；
+	// 仅 force 未生效 / ctx.expected 覆盖项缺失 / 形状违约会判失败。
+	const a = assertReloadApplied(r, { hasApi: hasApiModule(ctx.manifest), kind: "install", name: ctx.name, version: ctx.version, additional: ctx.expected, force: ctx.force === true });
+	if (!a.ok) {
+		return { stage: "reloading", ok: false, retryable: false, message: `热更失败：${a.message}` };
+	}
 	const pending = Array.isArray(r.restart_pending) && r.restart_pending.length > 0
-		? `；待重启段 [${r.restart_pending.join("、")}]（anonymous_paths 热改属 restart_pending，S1-5）`
+		? `；待重启段 [${r.restart_pending.join("、")}]（anonymous_paths / vars 等冻结·特权段热改属 restart_pending，v0.1.122）`
 		: "";
-	return { stage: "reloading", ok: true, message: `热更完成：generation ${r.generation ?? "?"}，已生效段 [${r.applied.join("、")}]${pending}` };
+	return { stage: "reloading", ok: true, message: `热更完成：generation ${r.generation ?? "?"}，已生效段 [${r.applied.join("、")}]${pending}`, restartPending: Array.isArray(r.restart_pending) ? r.restart_pending : [] };
 }