@oj-module/cli 0.2.2 → 0.2.6

package/templates/api/src/_platform/_lifecycle/trust.ts

@@ -0,0 +1,229 @@
+import { auditOp } from "../_shared/service/audit";
+// 宿主信任库（P2-2，契约 v1.3 §2.11 / C2-38/39，G3 双轨第一轨 / G5）。
+// 存储：.solutions/trusted-keys.yaml（key_id → {public_key, added_at}）——YAML 受限子集
+// （两层 map + 标量，同 state.ts 口径：只读回本模块写出的内容，不引 yaml 依赖，严格解析）。
+// 原子写（D13）+ .bak 前一版；主文件损坏自动回落 .bak 并留 note（下次写入自愈），
+// 两者皆坏 = 可读报错 fail-closed（含路径与修法指引，不半截数据）。
+// 首次绑定不可改（C2-38）：同 key_id 异公钥 = trust_bound_mismatch（409）；轮换 = 新增 key_id。
+// 吊销（C2-39/G5）= remove：只阻断新装/升级（P2-3/P2-6 消费），不动已装方案。
+// 空沙箱红线：模块级零全局触碰——fs 经 atomic.ts 的 fsFace()（globalThis.fs 平台注入），
+// audit 经注入面（缺省 auditOp，测试注入记录器）；禁 console（release isolate 抛 BadResource，Finding A）。
+import { atomicWriteText, fsFace } from "./atomic";
+
+export interface TrustEntry {
+	key_id: string
+	/** 32B raw 公钥 hex（契约 C2-35 public_key 口径） */
+	public_key: string
+	added_at: number
+}
+
+/** 审计出口形状（OpEntry 的相关子集；测试注入记录器，缺省 auditOp fire-and-forget） */
+export type TrustAudit = (entry: { action: string, module: string, target: string, detail: unknown, level?: number }) => void;
+
+/** 指纹面（sha256Hex(publicKey) 全 64 hex，契约 §2.11；缺省走运行时 crypto 增补面，测试注入） */
+export type FingerprintFn = (publicKeyHex: string) => string | null;
+
+export interface TrustStore {
+	list: () => Promise<TrustEntry[]>
+	/** 公钥 hex；不在库 = null */
+	get: (keyId: string) => Promise<string | null>
+	/** 新增信任；同 key 同公钥 = "exists_same"（幂等）；同 key 异公钥 = 拒（首次绑定不可改） */
+	add: (keyId: string, publicKeyHex: string, o?: { operator?: string | null }) => Promise<"added" | "exists_same">
+	/** 移除即吊销（G5）；返回是否有过该 key（审计留痕） */
+	remove: (keyId: string, o?: { operator?: string | null }) => Promise<boolean>
+	/** 最近一次读盘的损坏/回落 note（null = 正常；诊断观测出口，禁 console——Finding A） */
+	corruptNote?: () => string | null
+}
+
+/** C2-37 key_id 命名空间：<publisher>.<id> 全小写、至少一段点后缀；禁裸通用名（default/test/单段） */
+const KEY_ID = /^[a-z][a-z0-9-]*(?:\.[a-z0-9-]+)+$/;
+const PUBLIC_KEY_HEX = /^[0-9a-f]{64}$/;
+
+export function isValidKeyId(keyId: string): boolean {
+	return KEY_ID.test(keyId);
+}
+
+function fingerprintOf(publicKeyHex: string): string | null {
+	try {
+		const c = (globalThis as { crypto?: { sha256Hex?: (d: Uint8Array) => string } }).crypto;
+		const raw = new Uint8Array(32);
+		for (let i = 0; i < 32; i++)
+			raw[i] = Number.parseInt(publicKeyHex.slice(i * 2, i * 2 + 2), 16);
+		return c?.sha256Hex?.(raw) ?? null;
+	}
+	catch {
+		return null;
+	}
+}
+
+function bakPathOf(path: string): string {
+	return `${path}.bak`;
+}
+
+/** 带 status 的可读失败（respond 收口：err.status → json.fail，D14/B5/409 同一通道） */
+function failStatus(status: number, msg: string): never {
+	throw Object.assign(new Error(msg), { status });
+}
+
+/**
+ * 信任库工厂（同 state.ts：构造即读盘 hydrate；写路径每次从盘上最新内容读-改-写，多写者不丢键）。
+ * fs 走 atomic.ts fsFace()（globalThis.fs 平台注入/测试 stub，state.ts/lock.ts 同款 DIP）。
+ */
+export function createTrustStore(path: string, opts?: { audit?: TrustAudit, fingerprintOf?: FingerprintFn }): TrustStore {
+	const audit = opts?.audit ?? auditOp;
+	const fingerprint = opts?.fingerprintOf ?? fingerprintOf;
+	let note: string | null = null;
+
+	async function readDisk(): Promise<{ text: string | null, entries: Map<string, TrustEntry>, recovered: boolean }> {
+		const main = await readTextOrNull(path);
+		if (main !== null) {
+			try {
+				return { text: main, entries: parseTrust(main), recovered: false };
+			}
+			catch (e) {
+				// 主文件损坏：尝试 .bak 回落（自动恢复 + note，下次写入自愈）
+				const bak = await readTextOrNull(bakPathOf(path));
+				if (bak !== null) {
+					try {
+						return { text: bak, entries: parseTrust(bak), recovered: true };
+					}
+					catch {
+						// bak 也坏：落到底部统一报错
+					}
+				}
+				failStatus(500, `信任库损坏：${path} 无法解析（${String(e)}）且 ${bakPathOf(path)} 不可用——请按 key_id/公钥手工修复 YAML，或删除该文件后经 ojm trust add 重建；损坏期间拒绝一切信任变更（fail-closed）`);
+			}
+		}
+		return { text: null, entries: new Map(), recovered: false };
+	}
+
+	async function readTextOrNull(p: string): Promise<string | null> {
+		try {
+			return new TextDecoder().decode(await fsFace().readFile(p));
+		}
+		catch {
+			return null; // 不存在/不可读按缺失（读缺失不炸；isMissingPath 双形态由调用方不关心——空库语义）
+		}
+	}
+
+	async function commit(disk: { text: string | null, entries: Map<string, TrustEntry>, recovered: boolean }): Promise<void> {
+		const next = serializeTrust(disk.entries);
+		// .bak 只在主文件健康且内容将变时更新（recovered 时保住可用的 .bak 不覆盖）
+		if (!disk.recovered && disk.text !== null && disk.text !== next)
+			await atomicWriteText(bakPathOf(path), disk.text);
+		await atomicWriteText(path, next);
+		note = null; // 写成功即自愈：note 清零
+	}
+
+	return {
+		async list() {
+			const disk = await readDisk();
+			note = disk.recovered ? `${path} 损坏，已自动回落 ${bakPathOf(path)}（下次信任变更写入即自愈）` : null;
+			return [...disk.entries.values()].sort((a, b) => (a.key_id < b.key_id ? -1 : a.key_id > b.key_id ? 1 : 0));
+		},
+		async get(keyId) {
+			const disk = await readDisk();
+			return disk.entries.get(keyId)?.public_key ?? null;
+		},
+		corruptNote: () => note,
+		async add(keyId, publicKeyHex, o) {
+			if (!isValidKeyId(keyId))
+				failStatus(400, `key_id 格式非法（C2-37 命名空间 <publisher>.<id> 全小写、禁裸通用名）：${keyId}`);
+			if (!PUBLIC_KEY_HEX.test(publicKeyHex))
+				failStatus(400, `public_key 必须是 64 hex（Ed25519 32B raw）：${publicKeyHex.slice(0, 16)}…`);
+			const disk = await readDisk();
+			const existing = disk.entries.get(keyId);
+			if (existing !== undefined) {
+				if (existing.public_key === publicKeyHex)
+					return "exists_same"; // 幂等：不重写不审计
+				failStatus(409, `信任库首次绑定不可改（C2-38）：key_id「${keyId}」已绑定其他公钥（库内指纹 ${fingerprint(existing.public_key) ?? "?"} ≠ 新钥指纹 ${fingerprint(publicKeyHex) ?? "?"}）——轮换请新增 key_id，禁覆写`);
+			}
+			const next = new Map(disk.entries);
+			next.set(keyId, { key_id: keyId, public_key: publicKeyHex, added_at: Date.now() });
+			await commit({ ...disk, entries: next });
+			// operator 不可得 → 记 "unknown" 且告警级（level 4），不静默 null（P2-5）
+			const op = o?.operator ?? null;
+			audit({
+				action: "solution.trust.add",
+				module: "market",
+				target: keyId,
+				detail: { key_id: keyId, fingerprint: fingerprint(publicKeyHex), operator: op ?? "unknown" },
+				level: op ? 6 : 4,
+			});
+			return "added";
+		},
+		async remove(keyId, o) {
+			const disk = await readDisk();
+			if (!disk.entries.has(keyId))
+				return false; // 无此 key：无吊销可执行，不审计
+			const next = new Map(disk.entries);
+			next.delete(keyId);
+			await commit({ ...disk, entries: next });
+			// operator 不可得 → 记 "unknown" 且告警级（level 4），不静默 null（P2-5）
+			const op = o?.operator ?? null;
+			audit({
+				action: "solution.trust.revoke",
+				module: "market",
+				target: keyId,
+				detail: { key_id: keyId, operator: op ?? "unknown" },
+				level: op ? 6 : 4,
+			});
+			return true;
+		},
+	};
+}
+
+// ── 序列化/解析（严格受限子集，同 state.ts 口径）──────────────────────────────
+
+function serializeTrust(entries: Map<string, TrustEntry>): string {
+	const ids = [...entries.keys()].sort();
+	if (ids.length === 0) {
+		return "trusted_keys: {}\n";
+	}
+	const lines = ["trusted_keys:"];
+	for (const id of ids) {
+		const e = entries.get(id)!;
+		lines.push(
+			`  ${id}:`,
+			`    public_key: "${e.public_key}"`,
+			`    added_at: ${e.added_at}`,
+		);
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+/** 严格解析：首行 `trusted_keys:`/`trusted_keys: {}`，随后每组三行（键行/public_key/added_at），任何偏差 = 损坏 */
+function parseTrust(text: string): Map<string, TrustEntry> {
+	const lines = text.split("\n");
+	if (lines[lines.length - 1] === "") {
+		lines.pop();
+	}
+	if (lines.length === 0) {
+		throw new Error("空文件");
+	}
+	const entries = new Map<string, TrustEntry>();
+	if (lines[0] === "trusted_keys: {}") {
+		if (lines.length !== 1) {
+			throw new Error("「trusted_keys: {}」之后存在多余内容");
+		}
+		return entries;
+	}
+	if (lines[0] !== "trusted_keys:") {
+		throw new Error(`首行应为「trusted_keys:」，实为「${lines[0]}」`);
+	}
+	let i = 1;
+	while (i < lines.length) {
+		const keyId = /^ {2}([^:\s]+):$/.exec(lines[i])?.[1];
+		if (keyId === undefined) {
+			throw new Error(`第 ${i + 1} 行应为 key_id 行，实为「${lines[i]}」`);
+		}
+		const publicKey = /^ {4}public_key: "([0-9a-f]{64})"$/.exec(lines[i + 1] ?? "")?.[1];
+		const addedAt = /^ {4}added_at: (-?\d+)$/.exec(lines[i + 2] ?? "")?.[1];
+		if (publicKey === undefined || addedAt === undefined) {
+			throw new Error(`key「${keyId}」条目格式不完整或字段损坏`);
+		}
+		entries.set(keyId, { key_id: keyId, public_key: publicKey, added_at: Number(addedAt) });
+		i += 3;
+	}
+	return entries;
+}

package/templates/api/src/_platform/_lifecycle/types.ts

@@ -0,0 +1,94 @@
+// 生命周期编排面类型收敛（P1-10）：InstallContext 自 steps/preflight.ts 迁入（含可选 hostVersions，
+// C2-09 比对真源注入位）；StageResult 收敛为全 stage 通用结构形状（各 step 模块保留自己的字面量
+// stage 窄类型，结构相容即可赋值）；十阶段 InstallStage 名 = 契约附录 A 逐字（lock_commit 为
+// D11①扩展组）；TaskRecord = 注册设计 §10.2 形状 + stages 明细日志 + appliedSeq（对账 floor 依据）。
+
+import type { StateStore } from "./state";
+
+/** 安装上下文（各 step 模块 ctx 的公共基座；依赖注入面经各 step 的 ctx 扩展，见 steps/*） */
+export interface InstallContext {
+	/** 已解析的 manifest.yaml（安装器读盘解析产物） */
+	manifest: unknown
+	/** 安装目标身份（与 manifest.name/version 同源；manifest 字段缺失/非字符串时兜底） */
+	name: string
+	version: string
+	/** 站点 sidecar 状态（.solutions/state.yaml）；占用检测真源：solutions 键 = 已装方案名 */
+	state: StateStore
+	/** 宿主 versions.json（C2-09 peerRuntime 比对真源；键 = 包名，runtime 取 @oj-module/runtime） */
+	hostVersions?: Record<string, string>
+	/** 宿主平台编排面 API 版本（C2-11 peerPlatform 比对真源；镜像 GET /api/_platform/market/meta 的 apiVersion，即 market/api.ts 的 API_VERSION 常量，与 _platform/manifest.yaml 版本手工同步） */
+	hostApiVersion?: string
+	/** 目标站点数据库句柄（本段不消费；P1-8 register 段起使用） */
+	db?: unknown
+	/**
+	 * 同名重装/升级放行位（P1-10，AC-P1-3）：安装器检测到 sidecar 已有同名方案时置位——
+	 * 同名命中是本方案自己的升级路径（升级/降级 = runInstall({version})，任务简报），
+	 * 跨方案碰撞仍由 apiSeg/route_prefix 首段占用兜住；缺省 false 保持 P1-5「同名拒装」钉面。
+	 */
+	reinstall?: boolean
+}
+
+/** 阶段结果（全 stage 通用结构形状；stage 取值为各 step 自己的字面量，编排层以 StageDef.name 为准） */
+export interface StageResult {
+	stage: string
+	ok: boolean
+	message: string
+	retryable?: boolean
+	/** 取消安装（U5，P3-8）：本 stage 被用户中止，运行器据其走「清场 + 锁/目录回退装前 + 审计末位」语义 */
+	cancelled?: boolean
+	/** 签名失败六码（P2-3，契约附录 A.2；缺省 = 非签名类失败） */
+	code?: SigCode
+	/** 未知 key_id 待 TOFU 确认：任务停 needs_trust 终态，staging 不清场供确认后重试 */
+	needsTrust?: boolean
+	/** 待确认的发布方 key（TaskRecord.trust 同源；UI/CLI 展示指纹） */
+	trust?: { key_id: string, public_key: string, fingerprint: string }
+}
+
+/**
+ * 签名失败六码（契约 v1.3 附录 A.2，P2-3）：retryable 恒 false、零解压零落盘。
+ * 文案 key = `lifecycle.stage.verifying.<code>`（双语值 P2-5 落 locales）。
+ */
+export type SigCode = "sig_missing" | "sig_alg" | "sig_key" | "tampered" | "unknown_key" | "sig_format";
+
+/**
+ * 安装阶段名（契约附录 A 十阶段逐字 + D11①扩展组 lock_commit + audit/done 终态）。
+ * 附录 A 文案 key：`lifecycle.stage.<stage>.reason/.hint/.retryable`（audit 失败仅记日志不设 key）。
+ */
+export type InstallStage = "preflight" | "downloading" | "verifying" | "extracting" | "migrating" | "lock_commit" | "registering" | "deploying_web" | "reloading" | "smoke" | "audit" | "done";
+
+/**
+ * 任务状态（§10.2 三态 + partial：锁后失败部分生效——D11 失败语义② + needs_trust：
+ * 未知发布方 key_id 待人工 TOFU 确认——P2-3 第五终态，预锁段停止、staging 不清场，
+ * 确认入信任库后重试同一安装即可继续；一切消费面须把 needs_trust 当非成功态渲染）。
+ */
+export type TaskStatus = "running" | "done" | "failed" | "partial" | "needs_trust";
+
+/** 安装任务记录（§10.2 + stages 明细日志；落 .install-tasks/<id>.json，800ms 轮询消费面） */
+export interface TaskRecord {
+	/**
+	 * 记录 schema 版本（P2-10）：写方盖章（tasks.ts TASK_SCHEMA_VERSION）、读方回填（缺省=1，旧记录不炸）。
+	 * 升版纪律——加字段=minor（兼容：读方忽略未知字段）；改语义/删字段=major（不认识的高版本，
+	 * 读方须降级提示：人话提示 + 不误渲染成功）。与 CLI 侧 site.ts TASK_SCHEMA_VERSION_KNOWN 手工同步。
+	 */
+	schemaVersion?: number
+	id: string
+	name: string
+	version: string
+	status: TaskStatus
+	stage: InstallStage | null
+	/** 0-100 整体进度（按 STAGES 表完成数折算） */
+	progress: number
+	message: string
+	/** 各 stage 明细日志（UI 详情日志区数据源） */
+	stages: { stage: InstallStage, ok: boolean, message: string }[]
+	/** 失败/partial 终态：reason + retryable + 指引文案 key（契约附录 A） */
+	error?: { reason: string, retryable: boolean, hintKey?: string }
+	/** needs_trust 终态：待确认的发布方 key（POST /market/trust {task_id} 消费；指纹供人确认） */
+	trust?: { key_id: string, public_key: string, fingerprint: string }
+	startedAt: number
+	finishedAt?: number
+	/** 本次迁移 applied max seq（migrating 段捕获；reconcile 账本对账 floor 依据） */
+	appliedSeq?: number
+	/** 取消安装标记（U5，P3-8）：用户中止触发的终态（status 仍取 failed/partial——D11 共用失败终态，此标记供 UI 区分「取消」与「失败」） */
+	cancelled?: boolean
+}

package/templates/api/src/_platform/_lifecycle/uninstall.ts

@@ -0,0 +1,283 @@
+// 卸载编排器（P1-15a，SRP/OCP）：与 installer.ts 对称——安装 = runInstall，卸载 = runUninstall。
+// 端点（market/api.ts）只做门禁 + 取参 + 调本编排器，不重复编排（与 install 同纪律）。
+// 删除纪律（D12 反向，与 setEnabled 四处同写对称）：①锁摘除 ②sidecar 删条目 ③sys_solution_route 删
+// ④modules.json 删条目；另：权限唯一减法出口 uninstallSolution（双维度级联，solution-perms.ts）；
+// 版本目录移除；终态审计 + 全用户失效（权限已变，D10 撤销即强退）+ market_history 留痕。
+// 空锁拒启（S1-1.2）：摘除后锁为空 → 拒绝卸载最后一个模块（站点至少保留一个已锁模块）。
+// 任一步失败返回 {ok:false, message}（与 setEnabled 同纪律）；部分残差由 admin 重试或重装自愈。
+// SQL 全部参数化（与 audit.ts / setEnabled 同纪律，值不拼字符串）。
+
+import type { OpEntry } from "../_shared/service/audit";
+import type { StateStore } from "./state";
+import { invalidateAllUsers } from "../_shared/service/access";
+import { auditOp } from "../_shared/service/audit";
+import { uninstallSolution } from "../_shared/service/solution-perms";
+import { atomicWriteText, fsFace } from "./atomic";
+import { recordHistory } from "./history";
+import { readLock, writeLock } from "./lock";
+
+// db 为 oj isolate 注入全局（同模板 service 层惯例，installer.ts 同款；测试由夹具装 globalThis.db）
+declare const db: {
+	exec: (sql: string, params: unknown[]) => Promise<unknown>
+	query: (sql: string, params?: unknown[]) => Promise<unknown>
+	/** 当前方言（sqlite/mysql/pg）；缺省 sqlite。Q4 业务表目录查询方言无关 */
+	dialect?: () => string
+	/** 单一 DB 事务包裹（P3-3）：回调内语句共享一个 BEGIN/COMMIT/ROLLBACK 边界，异常即整段回滚 */
+	tx: <T>(fn: (t: { exec: (sql: string, params?: unknown[]) => Promise<unknown>, query: (sql: string, params?: unknown[]) => Promise<unknown> }) => Promise<T>) => Promise<T>
+};
+
+function isObj(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// P3-4（Q4 业务表保留提示）：卸载只删代码/锁/路由/sidecar/权限，绝不 DROP 业务数据；
+// 受影响业务表经双重来源得到——① manifest.tables 声明式权威源 ② 模块 slug 规范化前缀兜底扫描——
+// 仅回传「实际存在」的表名，供运维手工清理。检测全程失败静默兜底，不阻断卸载主流程。
+
+/** 从 manifest 文本抽取顶层 `tables:` 标量列表（manifest 形态稳定，避免引入 yaml 全局依赖） */
+function manifestTables(yamlText: string): string[] {
+	const out: string[] = [];
+	let inTables = false;
+	for (const raw of yamlText.split("\n")) {
+		const line = raw.replace(/\r$/, "");
+		if (!inTables) {
+			if (/^tables\s*:/.test(line)) {
+				inTables = true;
+				continue;
+			}
+			continue;
+		}
+		if (line.trim() === "")
+			continue;
+		const m = /^\s+-\s+(\S.*)$/.exec(line);
+		if (m) {
+			out.push(m[1].replace(/^['"]|['"]$/g, ""));
+			continue;
+		}
+		if (/^\S/.test(line))
+			break; // 顶层新键，tables 块结束
+	}
+	return out;
+}
+
+/** 当前方言（oj 注入 db.dialect，缺省 sqlite） */
+function currentDialect(): string {
+	const d = (db as { dialect?: () => string }).dialect;
+	return typeof d === "function" ? d() : "sqlite";
+}
+
+/** 表目录查询片段（方言无关：sqlite=sqlite_master，mysql/pg=information_schema） */
+export function catalogSpec(dialect: string): { existing: string, like: (pat: string) => [string, unknown[]] } {
+	if (dialect === "sqlite") {
+		return {
+			existing: "SELECT name FROM sqlite_master WHERE type='table'",
+			like: pat => ["SELECT name FROM sqlite_master WHERE type='table' AND name LIKE ? ESCAPE '!'", [pat]],
+		};
+	}
+	const schemaExpr = dialect === "mysql" ? "DATABASE()" : "'public'";
+	return {
+		existing: `SELECT table_name AS name FROM information_schema.tables WHERE table_schema = ${schemaExpr}`,
+		like: pat => [`SELECT table_name AS name FROM information_schema.tables WHERE table_schema = ${schemaExpr} AND table_name LIKE ? ESCAPE '!'`, [pat]],
+	};
+}
+
+/** 当前库实际存在的表名集合 */
+async function listExistingTables(dialect: string): Promise<Set<string>> {
+	const rows = (await db.query(catalogSpec(dialect).existing)) as Array<{ name: string }>;
+	return new Set(rows.map(r => r.name));
+}
+
+/** 模块 slug 规范化 + LIKE 转义（沿用 RBAC 权限命名空间约定：!%_ 转义，连字符→下划线作表前缀） */
+export function tablePrefixPattern(name: string): string {
+	const slug = name.replace(/-/g, "_").replace(/[!%_]/g, c => `!${c}`);
+	// 表名用下划线分隔（非权限码的 `.`）：slug_ + 通配符 %（末尾 % 不转义，保持通配语义）
+	return `${slug}_%`;
+}
+
+/** 收集需保留的业务表（Q4）：声明 + 前缀兜底；仅返回实际存在的表名 */
+export async function collectRetainedTables(name: string, manifestPath: string): Promise<string[]> {
+	const dialect = currentDialect();
+	const existing = await listExistingTables(dialect);
+	const candidates = new Set<string>();
+	// ① 声明式权威源：manifest.tables（通知等模块已在 manifest 声明业务表归属）
+	try {
+		const text = new TextDecoder().decode(await fsFace().readFile(manifestPath));
+		for (const t of manifestTables(text))
+			candidates.add(t);
+	}
+	catch {
+		// manifest 缺失（api-only 方案）→ 仅前缀兜底
+	}
+	// ② 前缀兜底：扫描当前库匹配模块前缀的表，覆盖未声明场景
+	try {
+		const [sql, params] = catalogSpec(dialect).like(tablePrefixPattern(name));
+		const rows = (await db.query(sql, params)) as Array<{ name: string }>;
+		for (const r of rows)
+			candidates.add(r.name);
+	}
+	catch {
+		// 兜底扫描失败不阻断卸载
+	}
+	return [...candidates].filter(t => existing.has(t));
+}
+
+/** 卸载影响面预检（GET uninstall-impact 消费面）：返回前端二次确认所需的影响计数 */
+export interface UninstallImpact {
+	name: string
+	affectedRoles: number
+	affectedUsers: number
+}
+
+export interface UninstallInput {
+	name: string
+	/** 可选显式版本；缺省回落锁/sidecar 版本 */
+	version?: string
+	sharedRoot: string
+	lockPath: string
+	state: StateStore
+	modulesJsonPath: string
+	/** 操作人（用户名，历史留痕；缺省 null） */
+	operator?: string | null
+	now?: number
+	/** 审计出口（缺省 auditOp；测试注入记录器） */
+	audit?: (entry: OpEntry) => void
+}
+
+export interface UninstallResult {
+	ok: boolean
+	message: string
+	/** P3-11 失败细分：not-installed = 方案已不存在（锁与 sidecar 均无记录）——端点据此回 404（资源缺失语义），其余拒绝仍 200 {ok:false} */
+	reason?: "not-installed"
+	/** P3-4（Q4）业务表保留清单：卸载不删业务数据，仅回传实际存在的业务表名供运维手工清理 */
+	retained?: string[]
+}
+
+/** 计算卸载影响面（角色数 + 持有这些角色的用户数） */
+export async function computeUninstallImpact(input: UninstallInput): Promise<UninstallImpact> {
+	const { name } = input;
+	const roles = await db.query("select name from sys_role where module = ?", [name]) as Array<{ name: string }>;
+	const roleNames = roles.map(r => r.name);
+	let affectedUsers = 0;
+	if (roleNames.length > 0) {
+		const rows = await db.query(
+			`select distinct user_id from sys_user_role where role_name in (${roleNames.map(() => "?").join(",")})`,
+			roleNames,
+		) as Array<{ user_id: number }>;
+		affectedUsers = rows.length;
+	}
+	return { name, affectedRoles: roleNames.length, affectedUsers };
+}
+
+/**
+ * 卸载编排（四处同删 + 权限级联 + 版本目录移除 + 审计 + 全用户失效 + 历史留痕）。
+ * 任一步失败返回 {ok:false, message}（操作已执行、被域逻辑拒绝，人话在 message，前端照 ok 位渲染，
+ * 与 setEnabled 同纪律）；锁/sidecar/route/modules 可能留部分残差（admin 手动重试或重装自愈）。
+ */
+export async function runUninstall(input: UninstallInput): Promise<UninstallResult> {
+	const { name } = input;
+	const f = fsFace();
+	const lock = await readLock(input.lockPath);
+	const side = input.state.read().solutions[name];
+
+	// 安装在哪：锁与 sidecar 均无记录 = 未安装（P3-11：细分 reason，端点据此回 404 资源缺失语义）
+	if (lock[name] === undefined && side === undefined) {
+		return { ok: false, reason: "not-installed", message: `卸载失败：「${name}」未安装（锁与 sidecar 均无记录）` };
+	}
+	const version = input.version ?? lock[name] ?? side?.version;
+	if (version === undefined) {
+		return { ok: false, message: `卸载失败：「${name}」版本不可得（锁与 sidecar 均无版本）` };
+	}
+
+	// 空锁拒启（S1-1.2）：摘除后锁为空 → 拒绝卸载最后一个模块
+	const remaining = { ...lock };
+	delete remaining[name];
+	if (Object.keys(remaining).length === 0) {
+		return { ok: false, message: "卸载失败：摘除后锁为空（空锁拒启，S1-1.2）——站点至少保留一个已锁模块，不能卸载最后一个" };
+	}
+
+	const audit = (ok: boolean, detail: string): void =>
+		(input.audit ?? auditOp)({ action: "solution.uninstall", module: name, target: name, detail: { ok, detail }, level: ok ? 6 : 4 });
+
+	// ① DB 级联单一事务（P3-3）：route 删除 + 权限双维度级联（uninstallSolution）纳入同一 BEGIN/COMMIT/ROLLBACK
+	// 边界。任一步失败 → 整段回滚（无角色/权限/路由半残），锁不摘（fail-closed：模块仍挂载、可重试或重装自愈）。
+	try {
+		await db.tx(async (t) => {
+			await t.exec("delete from sys_solution_route where module = ?", [name]);
+			await uninstallSolution(name, t);
+		});
+	}
+	catch (e) {
+		audit(false, `权限级联清理失败：${String(e)}`);
+		return { ok: false, message: `卸载失败：权限级联清理失败（${String(e)}）——事务已回滚，锁/路由/角色/权限未改动（fail-closed）` };
+	}
+
+	// ② sidecar 删条目（patch 值 null = 删除该方案键）
+	try {
+		await input.state.write({ solutions: { [name]: null } });
+	}
+	catch (e) {
+		audit(false, `sidecar 写失败：${String(e)}`);
+		return { ok: false, message: `卸载失败：sidecar 写失败（${String(e)}）——DB 级联已提交，锁未摘（fail-closed）` };
+	}
+
+	// ③ modules.json 删条目（条目不存在 = api-only 方案，天然一致）
+	try {
+		const list = JSON.parse(new TextDecoder().decode(await f.readFile(input.modulesJsonPath))) as unknown[];
+		if (!Array.isArray(list)) {
+			throw new TypeError("modules.json 顶层不是数组");
+		}
+		const next = list.filter(e => !(isObj(e) && e.name === name));
+		await atomicWriteText(input.modulesJsonPath, `${JSON.stringify(next, null, 2)}\n`);
+	}
+	catch (e) {
+		audit(false, `modules.json 写失败：${String(e)}`);
+		return { ok: false, message: `卸载失败：modules.json 写失败（${String(e)}）——DB 级联已提交、sidecar 已删，锁未摘（fail-closed）` };
+	}
+
+	// ① 锁摘除（最后执行：模块停止装配；在此之前任一失败锁均保留 = fail-closed）
+	try {
+		await writeLock(input.lockPath, remaining);
+	}
+	catch (e) {
+		audit(false, `锁写失败：${String(e)}`);
+		return { ok: false, message: `卸载失败：锁写失败（${String(e)}）——DB 级联/sidecar/modules 已更新，锁残留` };
+	}
+
+	// 版本目录移除（缺失不报错，幂等）
+	// —— 但 Q4 业务表清单须在版本目录移除前从 manifest 取得（manifest 在版本目录内）——
+	let retained: string[] = [];
+	try {
+		retained = await collectRetainedTables(name, `${input.sharedRoot}/${name}-${version}/manifest.yaml`);
+	}
+	catch {
+		retained = [];
+	}
+	try {
+		await f.remove(`${input.sharedRoot}/${name}-${version}`, { recursive: true });
+	}
+	catch {
+		// 目录缺失 = 已清理，忽略
+	}
+
+	// 权限已变 → 强退所有会话（D10：撤销即强退）
+	invalidateAllUsers();
+
+	// 终态审计
+	audit(true, `卸载完成：${name}@${version}`);
+
+	// 历史留痕（守卫式：表不存在/写失败静默，history.ts 同语义）
+	await recordHistory({
+		solution: name,
+		version,
+		action: "uninstall",
+		status: "success",
+		operator: input.operator ?? null,
+		message: `卸载完成：${name}@${version}`,
+	});
+
+	return {
+		ok: true,
+		message: `卸载完成：锁摘除 + sidecar + sys_solution_route + modules.json 四处同删 + 权限级联清理 + 版本目录移除（${name}@${version}）；业务表 ${retained.length} 张已保留（未删除，需运维手工清理）`,
+		retained,
+	};
+}