@oj-module/cli 0.2.2 → 0.2.6

package/templates/api/src/_platform/_lifecycle/steps/register.ts

@@ -0,0 +1,211 @@
+// 注册步骤（P1-8，十阶段 stage registering；D10 唯一出口）：安装器各 stage 之外任何人不得
+// 直写 sys_role/sys_permission/sys_setting/sys_solution_route 四类行——RBAC 经
+// upsertSolutionPerms 出口（AC2-1~6 原样消费，勿改其语义），设置/路由在本文件内收敛。
+// 语义纪律（镜像 solution-perms）：只做加法 + 元数据覆盖 + 声明消失行保留标 deprecated
+// （判决不突变，清单汇入返回值供安装器强告警 AC2-4）；设置项存在只覆定义列、管理员改过的
+// value 永不复活（AC1-15 同纪律）。本行拥有的行（路由/设置）upsert 时复位 deprecated=0——
+// 重声明行必须回到 queryRegistered 快照，否则 P1-9 冒烟对账假阴（solution-perms 出口未复位
+// 是其既有语义，本文件不越界代改）。DB 级路由占用检查承接 P1-5 备案③（pre-DB 阶段无真源）。
+// db 为 isolate 全局（同模板 service 层，无需 import；测试由夹具装 globalThis.db）。
+
+import type { SolutionManifest } from "../../_shared/service/solution-perms";
+import { auditOp } from "../../_shared/service/audit";
+import { upsertSolutionPerms } from "../../_shared/service/solution-perms";
+
+export interface RouteDecl {
+	path: string
+	/** D4 三值（settings/personal 已废弃） */
+	category: "main" | "admin" | "hidden"
+	order: number
+	title_key?: string
+	required_permission?: string
+}
+
+export interface SettingDecl {
+	key: string
+	group: string
+	type: string
+	/** 首装初值；缺省落 default_value */
+	value?: string
+	default_value?: string | null
+	label_key?: string | null
+	/** 组级 label_key（C2-22；P2-15③ G7 承载——declOf 此前丢弃，组标题落库回填） */
+	group_label_key?: string | null
+	/** enum 选项（契约 C2-24 string[] 的序列化产物） */
+	options?: string | null
+	secret?: boolean
+}
+
+export interface SolutionDecl extends SolutionManifest {
+	/** 版本上下文（审计 OpEntry.version；manifest 切片可缺省） */
+	version?: string
+	settings?: SettingDecl[]
+	routes?: RouteDecl[]
+}
+
+/** 阶段结果（各安装段通用形状，本段 stage 恒为 "registering"） */
+export interface StageResult {
+	stage: "registering"
+	ok: boolean
+	message: string
+	retryable?: boolean
+}
+
+export interface RegisterResult extends StageResult {
+	/** 本次被标 deprecated 的 code/name/key/path 清单（AC2-4 安装器强告警数据源） */
+	deprecated: string[]
+}
+
+/** 归一化快照（P1-9 冒烟对账消费；全排序、过滤 deprecated 行、零行全空返回 null） */
+export interface SolutionSnapshot {
+	module: string
+	routes: string[]
+	settings: string[]
+	roles: string[]
+	permissions: string[]
+}
+
+/** 首段提取（/wiki/docs → wiki）——占用判定粒度：前缀段冲突即整段首段比较（P1-5 备案③） */
+function firstSeg(path: string): string {
+	return path.split("/")[1] ?? "";
+}
+
+/**
+ * DB 级路由占用检查：返回已被其他 module 占用首段的声明路径清单。
+ * 框架保留段判断不做（那是 preflight 的活，C2-13/14）；deprecated 行仍算占用（行保留即占位，
+ * 让位须走卸载），自占排除（module ≠ 自己）。
+ */
+export async function checkOccupancy(module: string, routePaths: string[]): Promise<string[]> {
+	const rows = await db.query("select path from sys_solution_route where module != ?", [module]) as Array<{ path: string }>;
+	const taken = new Set(rows.map(r => firstSeg(String(r.path))));
+	return routePaths.filter(p => taken.has(firstSeg(p)));
+}
+
+/** 声明消失 → 行保留标 deprecated=1（镜像 solution-perms AC2-3/4），返回被标 key/path 清单 */
+async function deprecateGone(table: "sys_setting" | "sys_solution_route", col: "key" | "path", module: string, declared: Set<string>): Promise<string[]> {
+	const old = await db.query(`select ${col} from ${table} where module = ? and deprecated = 0`, [module]) as Array<Record<string, unknown>>;
+	const gone: string[] = [];
+	for (const r of old) {
+		const k = String(r[col]);
+		if (!declared.has(k)) {
+			await db.exec(`update ${table} set deprecated = 1 where ${col} = ?`, [k]);
+			gone.push(k);
+		}
+	}
+	return gone;
+}
+
+/**
+ * 注册一次完成（设计 §4 清单 #2/#3/#4）：占用预检 → RBAC 出口 → 设置 upsert → 路由 upsert
+ * → 声明消失标 deprecated → 审计。失败 StageResult{ok:false}：占用拒装零写入（retryable=false，
+ * 须改声明重打包）；DB 异常 retryable=true（附录 A registering）。
+ */
+export async function registerSolution(decl: SolutionDecl): Promise<RegisterResult> {
+	const routes = decl.routes ?? [];
+	const settings = decl.settings ?? [];
+	try {
+		// 占用预检（brief：registerSolution 开头先跑）：非空 → 拒注册零写入
+		const occupied = await checkOccupancy(decl.module, routes.map(r => r.path));
+		if (occupied.length > 0) {
+			return {
+				stage: "registering",
+				ok: false,
+				retryable: false,
+				deprecated: [],
+				message: `注册失败：路由首段已被其他方案占用（${occupied.join("、")}）——同站路由首段唯一，需调整声明后重新打包`,
+			};
+		}
+
+		// RBAC（唯一出口）：upsert + 声明消失标 deprecated，deprecated 清单原样汇入
+		const perms = await upsertSolutionPerms({ module: decl.module, roles: decl.roles });
+
+		// 设置项 upsert：存在只覆定义列（value/update 语义 = 管理员改过的值不复活，AC1-15），
+		// 不存在插 default_value（首装 value）
+		for (const s of settings) {
+			const exists = await db.query("select key from sys_setting where key = ?", [s.key]) as unknown[];
+			if (exists.length) {
+				await db.exec(
+					"update sys_setting set module = ?, \"group\" = ?, type = ?, default_value = ?, label_key = ?, group_label_key = ?, options = ?, secret = ?, deprecated = 0, update_time = ? where key = ?",
+					[decl.module, s.group, s.type, s.default_value ?? null, s.label_key ?? null, s.group_label_key ?? null, s.options ?? null, s.secret ? 1 : 0, Date.now(), s.key],
+				);
+			}
+			else {
+				await db.exec(
+					"insert into sys_setting (key, module, \"group\", type, value, default_value, label_key, group_label_key, options, secret, update_time, deprecated) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0)",
+					[s.key, decl.module, s.group, s.type, s.value ?? s.default_value ?? null, s.default_value ?? null, s.label_key ?? null, s.group_label_key ?? null, s.options ?? null, s.secret ? 1 : 0, Date.now()],
+				);
+			}
+		}
+		const settingDeps = await deprecateGone("sys_setting", "key", decl.module, new Set(settings.map(s => s.key)));
+
+		// 路由逐行 upsert：同 path 覆元数据；声明行复位 deprecated=0（重声明回到快照）
+		for (const r of routes) {
+			const exists = await db.query("select path from sys_solution_route where path = ?", [r.path]) as unknown[];
+			if (exists.length) {
+				await db.exec(
+					"update sys_solution_route set module = ?, category = ?, \"order\" = ?, title_key = ?, required_permission = ?, deprecated = 0 where path = ?",
+					[decl.module, r.category, r.order, r.title_key ?? null, r.required_permission ?? null, r.path],
+				);
+			}
+			else {
+				await db.exec(
+					"insert into sys_solution_route (path, module, category, \"order\", title_key, required_permission, deprecated, enabled) values (?, ?, ?, ?, ?, ?, 0, 1)",
+					[r.path, decl.module, r.category, r.order, r.title_key ?? null, r.required_permission ?? null],
+				);
+			}
+		}
+		const routeDeps = await deprecateGone("sys_solution_route", "path", decl.module, new Set(routes.map(r => r.path)));
+
+		const deprecated = [...perms.deprecated, ...settingDeps, ...routeDeps];
+		auditOp({
+			action: "solution.register",
+			module: decl.module,
+			version: decl.version,
+			target: decl.module,
+			detail: { routes: routes.length, settings: settings.length, deprecated },
+		});
+		return {
+			stage: "registering",
+			ok: true,
+			message: `注册完成：${decl.roles.length} 个角色、${settings.length} 个设置项、${routes.length} 条路由${deprecated.length > 0 ? `；${deprecated.length} 项声明消失已标 deprecated（需关注：${deprecated.join("、")}）` : ""}`,
+			deprecated,
+		};
+	}
+	catch (e) {
+		return { stage: "registering", ok: false, retryable: true, deprecated: [], message: `注册失败：${String(e)}（附录 A registering）` };
+	}
+}
+
+export async function queryRegistered(name: string): Promise<SolutionSnapshot | null> {
+	const routes = (await db.query("select path from sys_solution_route where module = ? and deprecated = 0", [name]) as Array<{ path: string }>).map(r => String(r.path)).sort();
+	const settings = (await db.query("select key from sys_setting where module = ? and deprecated = 0", [name]) as Array<{ key: string }>).map(r => String(r.key)).sort();
+	const roles = (await db.query("select name from sys_role where module = ? and deprecated = 0", [name]) as Array<{ name: string }>).map(r => String(r.name)).sort();
+	const permissions = (await db.query("select code from sys_permission where module = ? and deprecated = 0", [name]) as Array<{ code: string }>).map(r => String(r.code)).sort();
+	if (routes.length + settings.length + roles.length + permissions.length === 0) {
+		return null;
+	}
+	return { module: name, routes, settings, roles, permissions };
+}
+
+/**
+ * 全方案快照清单（P1-14 读面/深检对账辅助）：四表并集取模块名（queryRegistered 同款查询范式），
+ * 按 module 排序逐个快照；deprecated 行不计入存在性（同 queryRegistered 过滤口径），无行 → 空数组。
+ */
+export async function queryAllRegistered(): Promise<SolutionSnapshot[]> {
+	const names = new Set<string>();
+	for (const table of ["sys_solution_route", "sys_setting", "sys_role", "sys_permission"]) {
+		// 表名为字面常量，无拼接注入面
+		const rows = await db.query(`select distinct module from ${table} where deprecated = 0`) as Array<{ module: string }>;
+		for (const r of rows) {
+			names.add(String(r.module));
+		}
+	}
+	const out: SolutionSnapshot[] = [];
+	for (const name of [...names].sort()) {
+		const snap = await queryRegistered(name);
+		if (snap !== null) {
+			out.push(snap);
+		}
+	}
+	return out;
+}

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

@@ -0,0 +1,81 @@
+// 热更步骤（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/抛错三态。
+
+import type { InstallContext } from "./preflight";
+
+/** reloadConfig 返回形状（S1-5.2 实测五键；generation 可缺省容忍） */
+export interface ReloadResult {
+	generation?: number
+	unchanged: boolean
+	applied: string[]
+	restart_pending?: string[]
+	kept_listener?: string[]
+}
+
+export interface ReloadFace {
+	reloadConfig: () => Promise<ReloadResult>
+}
+
+export interface ReloadContext extends InstallContext {
+	/** 注入式 reload 面（生产 = platform 特权 server.reloadConfig 包装；测试 stub） */
+	reload: ReloadFace
+	/** 须实际生效的段键（R18 终态断言）；缺省 ["vars"]（B-11 安装触发面） */
+	expected?: string[]
+}
+
+export interface StageResult {
+	stage: "reloading"
+	ok: boolean
+	message: string
+	retryable?: boolean
+}
+
+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）` };
+	}
+	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)}`,
+		};
+	}
+	if (r.unchanged) {
+		return {
+			stage: "reloading",
+			ok: false,
+			retryable: false,
+			message: "热更失败：reloadConfig 返回 unchanged——config 改写未实际生效（R18 终态断言：幂等回显 = 热更目标未达成，重试不自愈），请检查 config 写入段后重试安装",
+		};
+	}
+	// 安装路径缺省期望 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));
+	if (missing.length > 0) {
+		return {
+			stage: "reloading",
+			ok: false,
+			retryable: false,
+			message: `热更失败：applied [${r.applied.join("、")}] 未含预期生效段 ${missing.join("、")}（R18：以 reload 返回的 mounts/vars 实际生效值做终态断言）`,
+		};
+	}
+	const pending = Array.isArray(r.restart_pending) && r.restart_pending.length > 0
+		? `；待重启段 [${r.restart_pending.join("、")}]（anonymous_paths 热改属 restart_pending，S1-5）`
+		: "";
+	return { stage: "reloading", ok: true, message: `热更完成：generation ${r.generation ?? "?"}，已生效段 [${r.applied.join("、")}]${pending}` };
+}

package/templates/api/src/_platform/_lifecycle/steps/smoke.ts

@@ -0,0 +1,216 @@
+// 冒烟步骤（P1-9，十阶段 stage smoke；设计 §4.1 四项之三 + 一项钉口径不实现），collect-all：
+// ①探活：manifest.health（C2-33）声明则探 <apiPrefix>/<health 去前导斜杠> 断言 2xx；缺省探首个
+//   **非匿名**路由同形 URL——连通即可不做语义断言（非匿名无凭证预期 401；D14/Q-A：health 不强制）。
+//   URL 形态与 C2-26 段内收敛一致：api 相对路径首段 = 模块段（fixture: health /demo-solution/ping
+//   ↔ anonymous demo-solution/ping）。无 health 无路由：无事可验视为通过。
+// ②integrity（R10：验签后包内容口径）：对**部署落位后**的 entry 文件重算 sha384 与 modules.json
+//   条目 integrity（sha384-<base64>，C2-28）相等；条目缺 integrity fail-closed（P1-10 必传，缺失即
+//   装配线破损）；声明 css 逐一验落位存在性（modules.json 单一 integrity 仅覆盖 entry——C2-28 构建
+//   器只对 entry 产物计算）。manifest 无 web 段本项不适用。
+// ③注册一致性：queryRegistered 快照（ctx.query 可注入，缺省回落 register.ts db 全局）vs 本次
+//   manifest 声明——升级态「包含非相等」：快照逐数组 ⊇ 声明全集（可多不可少，少 = 注册丢失判失败；
+//   相等当然过）；快照 null = 首装，声明全空过、非空败。
+// ④entry 浏览器加载不在安装器验（Node import 必假绿——设计 §4.1）：宿主 error boundary 兜底 +
+//   P2 深检可见，本步不实现，仅此处钉口径。
+// 任一失败不首条即停：三项全跑，原因逐项中文齐报（preflight 同纪律）。
+
+import type { InstallContext } from "./preflight";
+import type { SolutionSnapshot } from "./register";
+import { fsFace } from "../atomic";
+import { queryRegistered } from "./register";
+
+export interface SmokeContext extends InstallContext {
+	/** API 前缀（C2-13 api.prefix，缺省 /api/<name>；探针 URL 前缀，注入不硬编码） */
+	apiPrefix: string
+	/** 注入式探针 fetch 面（生产 = isolate 全局 fetch 同源调用；测试 stub 不真发请求） */
+	fetch: (url: string) => Promise<{ ok: boolean, status: number }>
+	/** 注入式 sha384 摘要面（base64 裸摘要，不带 sha384- 前缀；同 verify.ts DIP） */
+	sha384B64: (data: Uint8Array) => string
+	/** 站点 modules.json 路径（integrity 比对真源 + 落位文件定位基准：<dist>/modules.json） */
+	modulesJsonPath: string
+	/** 注册快照查询；缺省回落 queryRegistered（isolate db 全局；测试注入 stub） */
+	query?: (name: string) => Promise<SolutionSnapshot | null>
+}
+
+export interface StageResult {
+	stage: "smoke"
+	ok: boolean
+	message: string
+	retryable?: boolean
+}
+
+interface Failure {
+	item: string
+	reason: string
+	retryable: boolean
+}
+
+function isObj(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** 探针 URL 形态：<apiPrefix>/<path 去前导斜杠>（apiPrefix 尾斜杠归一；C2-26 段内收敛同构） */
+export function probeUrlOf(apiPrefix: string, path: string): string {
+	return `${apiPrefix.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+
+/** 首个非匿名路由 path：api.anonymous（相对路径）精确命中或前缀命中者跳过 */
+function firstNonAnonymousRoute(m: Record<string, unknown>): string | undefined {
+	const api = isObj(m.api) ? m.api : {};
+	const anonymous = Array.isArray(api.anonymous) ? api.anonymous.filter((a): a is string => typeof a === "string") : [];
+	const routes = Array.isArray(m.routes) ? m.routes : [];
+	for (const r of routes) {
+		if (!isObj(r) || typeof r.path !== "string") {
+			continue;
+		}
+		const rel = r.path.replace(/^\/+/, "");
+		if (!anonymous.some(a => rel === a || rel.startsWith(`${a}/`))) {
+			return r.path;
+		}
+	}
+	return undefined;
+}
+
+/** manifest 数组声明提取（routes[].path / roles[].name / permissions[].code） */
+function declaredStrings(m: Record<string, unknown>, key: string, field: string): string[] {
+	const list = Array.isArray(m[key]) ? m[key] : [];
+	const out: string[] = [];
+	for (const e of list) {
+		if (isObj(e) && typeof e[field] === "string") {
+			out.push(e[field]);
+		}
+	}
+	return out;
+}
+
+/** settings.groups[].items[].key 声明提取（C2-22 分组嵌套） */
+function declaredSettingKeys(m: Record<string, unknown>): string[] {
+	const s = m.settings;
+	if (!isObj(s) || !Array.isArray(s.groups)) {
+		return [];
+	}
+	const out: string[] = [];
+	for (const g of s.groups) {
+		if (!isObj(g) || !Array.isArray(g.items)) {
+			continue;
+		}
+		for (const it of g.items) {
+			if (isObj(it) && typeof it.key === "string") {
+				out.push(it.key);
+			}
+		}
+	}
+	return out;
+}
+
+interface ManifestEntry {
+	name?: string
+	entry?: string
+	css?: string[]
+	integrity?: string
+}
+
+export async function smoke(ctx: SmokeContext): Promise<StageResult> {
+	const failures: Failure[] = [];
+	const m = isObj(ctx.manifest) ? ctx.manifest : {};
+	const web = isObj(m.web) ? m.web : undefined;
+
+	// ① 探活：health 优先（2xx），缺省首个非匿名路由（连通即可）
+	try {
+		const health = typeof m.health === "string" && m.health !== "" ? m.health : undefined;
+		const target = health ?? firstNonAnonymousRoute(m);
+		if (target !== undefined) {
+			const url = probeUrlOf(ctx.apiPrefix, target);
+			const res = await ctx.fetch(url);
+			if (health !== undefined && !res.ok) {
+				failures.push({ item: "探活", retryable: true, reason: `health 端点 ${url} 返回 HTTP ${res.status}（C2-33 冒烟探针要求 2xx）` });
+			}
+		}
+	}
+	catch (e) {
+		failures.push({ item: "探活", retryable: true, reason: `探针请求失败（连通性不成立）：${String(e)}` });
+	}
+
+	// ② integrity：落位后重算 vs modules.json 条目（web 段存在才适用）
+	if (web !== undefined) {
+		try {
+			const f = fsFace();
+			const slash = ctx.modulesJsonPath.lastIndexOf("/");
+			const distRoot = slash === -1 ? "." : ctx.modulesJsonPath.slice(0, slash);
+			const list = JSON.parse(new TextDecoder().decode(await f.readFile(ctx.modulesJsonPath))) as ManifestEntry[];
+			const mine = Array.isArray(list) ? list.find((e: ManifestEntry) => isObj(e) && e.name === ctx.name) : undefined;
+			if (mine === undefined) {
+				failures.push({ item: "integrity", retryable: false, reason: `modules.json 无 ${ctx.name} 条目（部署清单缺位，deployWeb 未生效？）` });
+			}
+			else {
+				if (typeof mine.entry !== "string" || mine.entry === "") {
+					failures.push({ item: "integrity", retryable: false, reason: "modules.json 条目缺 entry（C2-27 web 段存在时必填）" });
+				}
+				if (typeof mine.integrity !== "string" || !mine.integrity.startsWith("sha384-")) {
+					failures.push({ item: "integrity", retryable: false, reason: "modules.json 条目缺 integrity（fail-closed：R10 要求基于包内容重算传入，缺失即装配线破损）" });
+				}
+				else if (typeof mine.entry === "string" && mine.entry !== "") {
+					const actual = `sha384-${ctx.sha384B64(await f.readFile(`${distRoot}/${mine.entry}`))}`;
+					if (actual !== mine.integrity) {
+						failures.push({ item: "integrity", retryable: false, reason: `entry 落位产物 sha384 与清单不符（R10 包内容口径）期望 ${mine.integrity} 实得 ${actual}` });
+					}
+				}
+				for (const c of Array.isArray(mine.css) ? mine.css : []) {
+					if (typeof c !== "string") {
+						continue;
+					}
+					try {
+						await f.readFile(`${distRoot}/${c}`);
+					}
+					catch {
+						failures.push({ item: "integrity", retryable: false, reason: `声明 css ${c} 未落位（部署不完整）` });
+					}
+				}
+			}
+		}
+		catch (e) {
+			failures.push({ item: "integrity", retryable: false, reason: `modules.json 不可读（${String(e)}）——部署清单缺位` });
+		}
+	}
+
+	// ③ 注册一致性：快照 ⊇ 声明（升级态「包含非相等」；null = 首装按声明空满判）
+	try {
+		const declared = {
+			routes: declaredStrings(m, "routes", "path"),
+			settings: declaredSettingKeys(m),
+			roles: declaredStrings(m, "roles", "name"),
+			permissions: declaredStrings(m, "permissions", "code"),
+		};
+		const snap = await (ctx.query ?? queryRegistered)(ctx.name);
+		if (snap === null) {
+			const total = declared.routes.length + declared.settings.length + declared.roles.length + declared.permissions.length;
+			if (total > 0) {
+				failures.push({ item: "注册一致性", retryable: false, reason: `注册快照为空（null）而本次声明 ${total} 项非空——声明未注册生效（D10 出口未落地？）` });
+			}
+		}
+		else {
+			for (const key of ["routes", "settings", "roles", "permissions"] as const) {
+				const have = new Set(snap[key]);
+				const missing = declared[key].filter(d => !have.has(d));
+				if (missing.length > 0) {
+					failures.push({ item: "注册一致性", retryable: false, reason: `快照 ${key} 缺少声明项（升级态「包含非相等」：快照可多不可少，少 = 注册丢失）：${missing.join("、")}` });
+				}
+			}
+		}
+	}
+	catch (e) {
+		failures.push({ item: "注册一致性", retryable: false, reason: `注册快照查询失败：${String(e)}` });
+	}
+
+	// ④ entry 浏览器加载不在安装器验（设计 §4.1）——无判定，口径钉于成功 message。
+
+	if (failures.length === 0) {
+		return { stage: "smoke", ok: true, message: "冒烟通过：探活 / integrity / 注册一致性 三项全过（entry 浏览器加载不在安装器验——设计 §4.1，宿主 error boundary + P2 深检兜底）" };
+	}
+	return {
+		stage: "smoke",
+		ok: false,
+		retryable: failures.every(x => x.retryable),
+		message: `冒烟未通过（${failures.length} 项失败，全量列出）：\n${failures.map(x => `- 【${x.item}】${x.reason}`).join("\n")}`,
+	};
+}