@oj-module/cli 0.2.2 → 0.2.5

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

@@ -0,0 +1,148 @@
+// oj 原生扁平锁 manifests.yaml（D12）+ 安装器任务互斥锁 .install-tasks/.lock（R17/R31）。
+// 锁格式严格 = `name: version` 字符串表（嵌套结构/额外键会解析失败拒启——禁加字段，S1-1.2/S1-3）；
+// 写 = 全量重写经 atomicWriteText，改写前备份原锁至 <lock>.bak（恢复 = 回拷 .bak，用例钉住）；
+// 写后读回校验重试收敛（S1-3 实测：oj build 的 load→save 窗口会吞并发外部写——不能假设 oj
+// 尊重安装器锁，oj 锁本体无互斥是 S1 实测结论，互斥是安装器自己的纪律）。
+// 任务互斥 = mkdir EEXIST 语义（O_CREAT|O_EXCL 的 POSIX 等价原语）：.lock 目录存在即占用；
+// owner.json 落持有者与时间戳，超时（默认 30min，R13 同款阈值）判 stale 可接管（持有者崩溃自愈）。
+
+import { atomicWriteText, fsFace, isMissingPath, randomId } from "./atomic";
+
+/** 解析扁平锁文本为 {name: version} 表。任何非 `name: version` 行都算坏锁（fail-closed，不猜）。 */
+export function parseLock(text: string): Record<string, string> {
+	const out: Record<string, string> = {};
+	for (const [i, line] of text.split("\n").entries()) {
+		if (line.trim() === "") {
+			continue;
+		}
+		const m = /^([\w.-]+): "?([\w.-]+)"?$/.exec(line);
+		if (m === null) {
+			throw new Error(`lock: manifests.yaml 第 ${i + 1} 行不是合法扁平锁条目（name: version）：「${line}」`);
+		}
+		out[m[1]] = m[2];
+	}
+	return out;
+}
+
+/** 序列化为 oj 原生扁平形态：键序排序、`name: version` 逐行（name/version 字符集均 yaml 安全可裸写） */
+export function serializeLock(entries: Record<string, string>): string {
+	const keys = Object.keys(entries).sort();
+	return keys.length === 0 ? "" : `${keys.map(k => `${k}: ${entries[k]}`).join("\n")}\n`;
+}
+
+/** 读锁：文件缺失视同空表（首装）；坏锁（解析失败）原样上抛由调用方给可读报错。 */
+export async function readLock(lockPath: string): Promise<Record<string, string>> {
+	try {
+		return parseLock(new TextDecoder().decode(await fsFace().readFile(lockPath)));
+	}
+	catch (e) {
+		if (isMissingPath(e)) {
+			return {};
+		}
+		throw e;
+	}
+}
+
+/**
+ * 全量重写锁（D12）：改写前备份原锁至 <lock>.bak（原锁不存在则无备份可做）；拒绝空锁
+ * （空锁拒启，S1-1.2 实测 oj exit 1）——摘除最后一个条目必须被拒绝，站点至少保留一个已锁模块。
+ */
+export async function writeLock(lockPath: string, entries: Record<string, string>): Promise<void> {
+	if (Object.keys(entries).length === 0) {
+		throw new Error("lock: 拒绝写入空锁（空锁拒启，S1-1.2）——站点至少保留一个已锁模块");
+	}
+	const f = fsFace();
+	try {
+		await f.readFile(lockPath);
+		await f.copyFile(lockPath, `${lockPath}.bak`);
+	}
+	catch (e) {
+		if (!isMissingPath(e)) {
+			throw e;
+		}
+	}
+	await atomicWriteText(lockPath, serializeLock(entries));
+}
+
+export interface LockCommitResult {
+	ok: boolean
+	message: string
+}
+
+/**
+ * upsert 单条目并读回校验（S1-3 读回收敛）：读最新 → upsert → .bak → 原子写 → 读回，条目被
+ * 并发写者吞掉则重试（默认 3 次），仍失败给附录 A lock_commit 语义（retryable：存在并发构建或安装）。
+ */
+export async function commitLockEntry(lockPath: string, name: string, version: string, retries = 3): Promise<LockCommitResult> {
+	for (let i = 1; i <= retries; i++) {
+		const entries = await readLock(lockPath);
+		entries[name] = version;
+		await writeLock(lockPath, entries);
+		const back = await readLock(lockPath);
+		if (back[name] === version) {
+			return { ok: true, message: `manifests.yaml upsert ${name}: ${version}（写后读回校验通过）` };
+		}
+	}
+	return {
+		ok: false,
+		message: `生效切换失败：锁写后读回 ${retries} 次均不符（条目 ${name} 被并发写者吞写，S1-3）——附录 A lock_commit：存在并发构建或安装，请稍后重试`,
+	};
+}
+
+export interface TaskLock {
+	release: () => Promise<void>
+}
+
+/** stale 阈值：与任务超时判 failed 同款 30min（R13/B9/R31 口径一致） */
+export const LOCK_STALE_MS = 30 * 60_000;
+
+export interface TaskLockOptions {
+	/** 占用判定过期阈值（默认 30min；持有者崩溃后可接管） */
+	staleMs?: number
+	now?: number
+}
+
+/**
+ * 取安装任务互斥锁（R17/R31）：.lock 目录 mkdir EEXIST 为原子闸；owner.json 记持有者与时间戳。
+ * 并发第二取锁抛 busy；持有者崩溃后 owner 时间戳超 staleMs 可接管（stale takeover）。
+ * owner.json 缺失/不可读（mkdir 与写 owner 之间的崩溃窗口）无法证明 stale，按占用拒绝——
+ * 窗口极窄且可人工清除（删 .lock 目录），不给并发误判留口。
+ */
+export async function acquireTaskLock(taskDir: string, opts: TaskLockOptions = {}): Promise<TaskLock> {
+	const f = fsFace();
+	const dir = `${taskDir}/.lock`;
+	await f.mkdir(taskDir, { recursive: true });
+	const now = opts.now ?? Date.now();
+	const staleMs = opts.staleMs ?? LOCK_STALE_MS;
+	let owner: { holder?: string, acquiredAt?: number } | undefined;
+	try {
+		owner = JSON.parse(new TextDecoder().decode(await f.readFile(`${dir}/owner.json`)));
+	}
+	catch {
+		// 无 owner.json：目录裸建或不存在——不可证明 stale，走 mkdir 闸判定
+	}
+	if (typeof owner?.acquiredAt === "number") {
+		if (now - owner.acquiredAt < staleMs) {
+			throw new Error(`install busy：已有安装任务持锁（${dir}，holder ${owner.holder ?? "?"}）——R17/R31 互斥；持有者崩溃后约 ${Math.round(staleMs / 60000)} 分钟可接管`);
+		}
+		await f.remove(dir, { recursive: true }); // stale 接管
+	}
+	try {
+		await f.mkdir(dir);
+	}
+	catch {
+		throw new Error(`install busy：已有安装任务持锁（${dir}）——R17/R31 互斥`);
+	}
+	await f.writeFile(`${dir}/owner.json`, new TextEncoder().encode(JSON.stringify({ holder: randomId(), acquiredAt: now })));
+	return {
+		async release(): Promise<void> {
+			// 释放失败不掩盖主流程结果（.lock 残留由 stale 接管自愈）
+			try {
+				await f.remove(dir, { recursive: true });
+			}
+			catch {
+				// ponytail: 单持有者纪律，不校验 owner 归属；多写者场景需先验 holder 再删
+			}
+		},
+	};
+}

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

@@ -0,0 +1,61 @@
+// semver 比较器（R25）：纯字符串解析、无依赖。
+// 容错口径：允许缺省段（「1.0」=「1.0.0.0」，缺省视为 0）。
+// prerelease 遵循 semver 2.0.0：数字标识符按数值、字母按字典序、数字 < 字母、
+// 标识符列表前缀相等时多者大；无 prerelease > 有 prerelease。
+
+function splitVersion(v: string): { core: number[], pre: string[] | null } {
+	const hyphen = v.indexOf("-");
+	const core = hyphen === -1 ? v : v.slice(0, hyphen);
+	const prePart = hyphen === -1 ? null : v.slice(hyphen + 1);
+	const coreParts = core.split(".");
+	const pre = prePart == null ? null : prePart.split(".");
+	return {
+		// 容错口径：非数字段（如 "1.0.x" 的 "x"）静默归零，不抛错
+		core: coreParts.map(seg => Number.parseInt(seg, 10) || 0),
+		pre,
+	};
+}
+
+function comparePrerelease(a: string[] | null, b: string[] | null): -1 | 0 | 1 {
+	// 无 prerelease > 有 prerelease
+	if (a === null || b === null) {
+		return a === b ? 0 : a === null ? 1 : -1;
+	}
+	const len = Math.max(a.length, b.length);
+	for (let i = 0; i < len; i++) {
+		const ia = a[i];
+		const ib = b[i];
+		// 前缀相等时，标识符多者大
+		if (ia === undefined)
+			return -1;
+		if (ib === undefined)
+			return 1;
+		const na = /^\d+$/.test(ia);
+		const nb = /^\d+$/.test(ib);
+		if (na && nb) {
+			const diff = Number.parseInt(ia, 10) - Number.parseInt(ib, 10);
+			if (diff !== 0)
+				return diff < 0 ? -1 : 1;
+		}
+		else if (na !== nb) {
+			// 数字 < 字母
+			return na ? -1 : 1;
+		}
+		else if (ia !== ib) {
+			return ia < ib ? -1 : 1;
+		}
+	}
+	return 0;
+}
+
+export function compareVersions(a: string, b: string): -1 | 0 | 1 {
+	const va = splitVersion(a);
+	const vb = splitVersion(b);
+	const len = Math.max(va.core.length, vb.core.length);
+	for (let i = 0; i < len; i++) {
+		const diff = (va.core[i] ?? 0) - (vb.core[i] ?? 0);
+		if (diff !== 0)
+			return diff < 0 ? -1 : 1;
+	}
+	return comparePrerelease(va.pre, vb.pre);
+}

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

@@ -0,0 +1,187 @@
+// 过渡实现：上游 crypto.sha384 原语落地后替换（需求稿已提，见
+// docs/prd/solution/202610161500-oj-bin-feature-requests-pr.md）。
+// 纯 JS SHA-384（B-11 真机补面）：oj isolate 的 crypto 面（0.1.78 实测）只有
+// sha256Hex/md5Hex/aesGcm/verifyEd25519，无 sha384 原语；而契约 C2-28 的 web.integrity
+// 钉死 `sha384-<base64>`（ojm build 于 Node 侧写入），安装器必须同算法重算比对（R10
+// fail-closed）——真机冒烟首轮死于 `crypto.sha384B64 is not a function`。实现取 SHA-512
+// 核心（sha384 = 截断 48 字节 + 独立 IV），hi/lo 双 Uint32 字实现（BigInt 版逐块 80 轮在
+// MB 级产物上不可接受）。K/IV 常量表不在代码里摊开：模块加载时由素数平方根/立方根小数
+// 部分推导（FIPS 180-4 定义式，一次性 <1ms，逐字等于手抄表）。
+
+/** 前 count 个素数（2 起）——K/IV 的种子，N=80 时最坏几百次试除，加载期一次性 */
+function primes(count: number): bigint[] {
+	const out: bigint[] = [];
+	for (let n = 2n; out.length < count; n++) {
+		let isPrime = true;
+		for (const p of out) {
+			if (p * p > n)
+				break;
+			if (n % p === 0n) {
+				isPrime = false;
+				break;
+			}
+		}
+		if (isPrime)
+			out.push(n);
+	}
+	return out;
+}
+
+/** floor((x << (64·root)) ** (1/root)) 的低 64 位：FIPS 180-4 常量 = 素数 root 次根小数部分前 64 位。二分整根（≤66 步），加载期一次性 */
+function frac64(x: bigint, root: bigint): [number, number] {
+	const shift = x << (64n * root);
+	let lo = 0n;
+	let hi = 16n << 64n; // 上界：素数 ≤ 409 ⇒ root 次根 = cbrt(p)·2^64 < 16·2^64
+	while (lo < hi) {
+		const mid = (lo + hi + 1n) >> 1n;
+		if (mid ** root <= shift)
+			lo = mid;
+		else
+			hi = mid - 1n;
+	}
+	const low64 = lo & ((1n << 64n) - 1n);
+	return [Number(low64 >> 32n) >>> 0, Number(low64 & 0xFFFFFFFFn) >>> 0];
+}
+
+// K = 前 80 个素数的立方根小数部分前 64 位（FIPS 180-4 §4.2.3 定义式推导，逐字等于手抄表）。
+const K: Array<[number, number]> = primes(80).map(p => frac64(p, 3n));
+// sha384 IV（FIPS 180-4 §5.3.4 逐字）：8 × 64bit，hi/lo 对
+const IV: Array<[number, number]> = [
+	[0xCBBB9D5D, 0xC1059ED8],
+	[0x629A292A, 0x367CD507],
+	[0x9159015A, 0x3070DD17],
+	[0x152FECD8, 0xF70E5939],
+	[0x67332667, 0xFFC00B31],
+	[0x8EB44A87, 0x68581511],
+	[0xDB0C2E0D, 0x64F98FA7],
+	[0x47B5481D, 0xBEFA4FA4],
+];
+
+const MASK = 0xFFFFFFFF;
+
+/** rotr(x, n) 作用在 hi/lo 合成 64 位上（拆移位组合，无 BigInt 热路径） */
+function rotrHi(hi: number, lo: number, n: number): number {
+	if (n === 32)
+		return hi;
+	if (n < 32)
+		return ((hi >>> n) | (lo << (32 - n))) & MASK;
+	return ((lo >>> (n - 32)) | (hi << (64 - n))) & MASK;
+}
+function rotrLo(hi: number, lo: number, n: number): number {
+	if (n === 32)
+		return lo;
+	if (n < 32)
+		return ((lo >>> n) | (hi << (32 - n))) & MASK;
+	return ((hi >>> (n - 32)) | (lo << (64 - n))) & MASK;
+}
+
+/**
+ * 64 位加法（hi/lo 对，进位取模 2^32）。入参低位先 >>> 0 归一：上游 XOR/rotr 链会漏出
+ * 负 int32（& MASK 不改符号位），进位判定 lo < alo 在负数输入下恒假 → 丢进位（真机向量首轮实测）
+ */
+function add64(a: [number, number], b: [number, number]): [number, number] {
+	const alo = a[1] >>> 0;
+	const blo = b[1] >>> 0;
+	const lo = (alo + blo) >>> 0;
+	const carry = lo < alo ? 1 : 0;
+	return [(a[0] + b[0] + carry) & MASK, lo];
+}
+
+/** SHA-384 字节摘要（48 字节）；data = 任意长度字节序列 */
+export function sha384Bytes(data: Uint8Array): Uint8Array {
+	// 消息填充：0x80 + 0x00... + 128bit 长度（bit 数）
+	const bitLenHi = Math.floor((data.length / 0x20000000)) >>> 0;
+	const bitLenLo = (data.length << 3) >>> 0;
+	const padded = (((data.length + 16) >> 7) + 1) << 7;
+	const buf = new Uint8Array(padded);
+	buf.set(data);
+	buf[data.length] = 0x80;
+	const view = new DataView(buf.buffer);
+	view.setUint32(padded - 16, bitLenHi);
+	view.setUint32(padded - 4, bitLenLo);
+
+	const h: Array<[number, number]> = IV.map(x => [x[0], x[1]] as [number, number]);
+	const w = Array.from({ length: 80 });
+	for (let off = 0; off < padded; off += 128) {
+		for (let t = 0; t < 16; t++) {
+			w[t] = [view.getUint32(off + t * 8), view.getUint32(off + t * 8 + 4)];
+		}
+		for (let t = 16; t < 80; t++) {
+			// σ0 = ROTR1 ^ ROTR8 ^ SHR7；σ1 = ROTR19 ^ ROTR61 ^ SHR6。SHR 低字必须从 hi 的低位
+			// 补进 hi<<(32-n)（64 位逻辑右移跨字，非两次独立 32 位移位——差此项向量不过，差分实测）
+			const a15 = w[t - 15];
+			const a2 = w[t - 2];
+			const s0h = rotrHi(a15[0], a15[1], 1) ^ rotrHi(a15[0], a15[1], 8) ^ (a15[0] >>> 7);
+			const s0l = rotrLo(a15[0], a15[1], 1) ^ rotrLo(a15[0], a15[1], 8) ^ ((a15[1] >>> 7) | (a15[0] << 25));
+			const s1h = rotrHi(a2[0], a2[1], 19) ^ rotrHi(a2[0], a2[1], 61) ^ (a2[0] >>> 6);
+			const s1l = rotrLo(a2[0], a2[1], 19) ^ rotrLo(a2[0], a2[1], 61) ^ ((a2[1] >>> 6) | (a2[0] << 26));
+			w[t] = add64(add64(add64(w[t - 16], [s0h, s0l]), w[t - 7]), [s1h, s1l]);
+		}
+		let [ah, al] = h[0];
+		let [bh, bl] = h[1];
+		let [ch, cl] = h[2];
+		let [dh, dl] = h[3];
+		let [eh, el] = h[4];
+		let [fh, fl] = h[5];
+		let [gh, gl] = h[6];
+		let [hh, hl] = h[7];
+		for (let t = 0; t < 80; t++) {
+			// S1 = Σ6(e)，ch = (e&f)^(~e&g)，T1 = h + S1 + ch + K[t] + w[t]
+			const s1h = rotrHi(eh, el, 14) ^ rotrHi(eh, el, 18) ^ rotrHi(eh, el, 41);
+			const s1l = rotrLo(eh, el, 14) ^ rotrLo(eh, el, 18) ^ rotrLo(eh, el, 41);
+			const chh = (eh & fh) ^ (~eh & gh) & MASK;
+			const chl = (el & fl) ^ (~el & gl) & MASK;
+			const t1 = add64(add64(add64(add64([hh, hl], [s1h, s1l]), [chh, chl]), K[t]), w[t]);
+			// S0 = Σ0(a)，maj = (a&b)^(a&c)^(b&c)，T2 = S0 + maj
+			const s0h = rotrHi(ah, al, 28) ^ rotrHi(ah, al, 34) ^ rotrHi(ah, al, 39);
+			const s0l = rotrLo(ah, al, 28) ^ rotrLo(ah, al, 34) ^ rotrLo(ah, al, 39);
+			const majh = (ah & bh) ^ (ah & ch) ^ (bh & ch);
+			const majl = (al & bl) ^ (al & cl) ^ (bl & cl);
+			const t2 = add64([s0h, s0l], [majh, majl]);
+			hh = gh;
+			hl = gl;
+			gh = fh;
+			gl = fl;
+			fh = eh;
+			fl = el;
+			[eh, el] = add64([dh, dl], t1);
+			dh = ch;
+			dl = cl;
+			ch = bh;
+			cl = bl;
+			bh = ah;
+			bl = al;
+			[ah, al] = add64(t1, t2);
+		}
+		h[0] = add64(h[0], [ah, al]);
+		h[1] = add64(h[1], [bh, bl]);
+		h[2] = add64(h[2], [ch, cl]);
+		h[3] = add64(h[3], [dh, dl]);
+		h[4] = add64(h[4], [eh, el]);
+		h[5] = add64(h[5], [fh, fl]);
+		h[6] = add64(h[6], [gh, gl]);
+		h[7] = add64(h[7], [hh, hl]);
+	}
+	// 截断 48 字节 = 前 6 个字
+	const out = new Uint8Array(48);
+	const ov = new DataView(out.buffer);
+	for (let i = 0; i < 6; i++) {
+		ov.setUint32(i * 8, h[i][0]);
+		ov.setUint32(i * 8 + 4, h[i][1]);
+	}
+	return out;
+}
+
+/** bytes → base64（btoa 双端可用：oj isolate 全局 atob/btoa，Node 18+ 同名全局） */
+export function bytesToBase64(bytes: Uint8Array): string {
+	let bin = "";
+	for (const b of bytes) {
+		bin += String.fromCharCode(b);
+	}
+	return btoa(bin);
+}
+
+/** C2-28/R10 完整 integrity 值：`sha384-<base64(digest)>` */
+export function sha384B64(data: Uint8Array): string {
+	return `sha384-${bytesToBase64(sha384Bytes(data))}`;
+}

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

@@ -0,0 +1,256 @@
+// sidecar 状态存储（D12）：.solutions/state.yaml 读写——enabled/时间戳/GC 元数据
+// 不进 oj 原生扁平锁（manifests.yaml 嵌套结构会拒启），全部落这里。
+// YAML 采用受限子集（两层 map + 标量，键序固定、方案键排序输出），格式形如：
+//
+//   solutions:
+//     demo:
+//       version: "1.0.0"
+//       enabled: true
+//       installedAt: 1730000000000
+//       archive: "{\"sha256\":\"…\",\"key_id\":\"…\",\"signature\":{…}}"   # P2-6 复验真源（JSON 字符串标量）
+//       trust_state: trusted                                            # P2-6 发布方 key 状态缓存
+//
+// 只保证读回本模块自己写出的内容，不引入 yaml 依赖；任何不符格式的字节一律视为
+// 损坏 → 空状态，损坏上下文并入读结果（corruptNote/corruptReason；禁 console——release
+// isolate console 抛 BadResource，Finding A；不炸，write 会以 patch 为基自愈重写）。
+// read() 返回工厂 hydrate 时的同步快照（逐条目克隆，调用方改动不影响 store）；
+// write() 每次从盘上最新内容做读-改-写合并（多写者不丢彼此的方案键），
+// patch 值为 null 表示删除该方案键（GC/卸载的删除出口）。
+// fs 依赖同 atomic.ts（globalThis.fs 面）。
+
+import { atomicWriteText, fsFace } from "./atomic";
+
+export interface SolutionEntry {
+	version: string
+	enabled: boolean
+	installedAt: number
+	/**
+	 * P2-6 复验真源：安装时落的包摘要 + 签名记录（D11③ 切换前复验 / 同版本重装摘要比对）。
+	 * JSON 字符串标量落盘（两层 YAML 约束保持）；P1 时代条目无此字段 = 无验签真源。
+	 */
+	archive?: { sha256: string, key_id: string, signature: Record<string, unknown> }
+	/** 发布方 key 状态缓存（P2-6：安装=trusted；启用时 key 已吊销=untrusted；P1 时代条目=absent） */
+	trust_state?: "trusted" | "untrusted" | "absent"
+	/** P3-2 版本时间序记录（GC 依据）：成功安装的版本按 installedAt 倒序（最新在前），保留最近 N=3 + 锁版本强制保留 */
+	history?: Array<{ version: string, installedAt: number }>
+}
+
+export interface SolutionState {
+	solutions: Record<string, SolutionEntry>
+}
+
+export interface StateStore {
+	read: () => SolutionState
+	write: (patch: Partial<SolutionState>) => Promise<void>
+	/** 最近一次盘上读到的损坏 note（null = 未损坏；诊断观测出口，禁 console——Finding A；可选，测试 stub 免实现） */
+	corruptNote?: () => string | null
+}
+
+const EMPTY: SolutionState = { solutions: {} };
+
+/**
+ * 快照克隆：oj isolate 无 structuredClone（P1-13 真机冒烟实测 500，契约附录 B-8）；
+ * 状态形状是受限子集（string/bool/number 的两层 map），逐条目浅拷贝即达「调用方改动不影响 store」。
+ */
+function snapshot(state: SolutionState): SolutionState {
+	const solutions: Record<string, SolutionEntry> = {};
+	for (const [name, entry] of Object.entries(state.solutions)) {
+		// archive 是嵌套对象：逐层克隆（调用方改动不得影响 store 缓存；P2-6 复验真源）
+		const cloned: SolutionEntry = { ...entry };
+		if (entry.archive !== undefined) {
+			cloned.archive = { ...entry.archive, signature: { ...entry.archive.signature } };
+		}
+		// P3-2 history 数组：浅克隆（条目为标量态，调用方改动不影响 store 缓存）
+		if (entry.history !== undefined) {
+			cloned.history = entry.history.map(h => ({ ...h }));
+		}
+		solutions[name] = cloned;
+	}
+	return { solutions };
+}
+
+/**
+ * 工厂为 async：构造时从盘上 hydrate 一次，之后 read() 走同步快照（平台 fs 面纯异步，同步 read 只能基于缓存）。
+ * 需要观察外部更新的场景重建工厂即可（安装流程一次性构造，无长生命周期需求）。
+ */
+export async function createStateStore(path: string): Promise<StateStore> {
+	let disk = await readDisk(path);
+	let cache = disk.state;
+	let note = disk.corruptReason;
+	return {
+		read: () => snapshot(cache),
+		corruptNote: () => note,
+		async write(patch: Partial<SolutionState>): Promise<void> {
+			disk = await readDisk(path);
+			note = disk.corruptReason;
+			const solutions: Record<string, SolutionEntry> = { ...disk.state.solutions };
+			// patch 值运行时放宽允许 null（类型收窄见调用侧）：null = 删除该方案键
+			const patchSolutions: Record<string, SolutionEntry | null> | undefined = patch.solutions;
+			if (patchSolutions !== undefined) {
+				for (const [name, entry] of Object.entries(patchSolutions)) {
+					if (entry === null) {
+						delete solutions[name];
+					}
+					else {
+						solutions[name] = entry;
+					}
+				}
+			}
+			const next: SolutionState = { solutions };
+			const text = serializeState(next); // 守卫先跑：任一条目非法即整次拒绝，盘与缓存都不动
+			await atomicWriteText(path, text);
+			note = null; // 写成功即自愈：损坏 note 清零（下次读以盘上真身为准）
+			cache = next;
+		},
+	};
+}
+
+async function readDisk(path: string): Promise<{ state: SolutionState, corrupted: boolean, corruptReason: string | null }> {
+	let text: string;
+	try {
+		text = new TextDecoder().decode(await fsFace().readFile(path));
+	}
+	catch {
+		// 不存在/不可读一律按空状态（读缺失文件不炸）
+		return { state: EMPTY, corrupted: false, corruptReason: null };
+	}
+	try {
+		return { state: parseState(text), corrupted: false, corruptReason: null };
+	}
+	catch (e) {
+		// 损坏上下文并入读结果（store.corruptNote 出口；禁 console——release isolate console 抛 BadResource，Finding A）
+		return { state: EMPTY, corrupted: true, corruptReason: `${path} 不是本模块写出的合法状态文件，按空状态处理（${String(e)}）` };
+	}
+}
+
+function serializeState(state: SolutionState): string {
+	const names = Object.keys(state.solutions).sort();
+	if (names.length === 0) {
+		return "solutions: {}\n";
+	}
+	const lines = ["solutions:"];
+	for (const name of names) {
+		const e = state.solutions[name];
+		assertEntry(name, e);
+		lines.push(
+			`  ${name}:`,
+			`    version: ${JSON.stringify(e.version)}`,
+			`    enabled: ${e.enabled}`,
+			`    installedAt: ${e.installedAt}`,
+		);
+		if (e.archive !== undefined) {
+			lines.push(`    archive: ${JSON.stringify(JSON.stringify(e.archive))}`);
+		}
+		if (e.trust_state !== undefined) {
+			lines.push(`    trust_state: ${e.trust_state}`);
+		}
+		if (e.history !== undefined) {
+			lines.push(`    history: ${JSON.stringify(JSON.stringify(e.history))}`);
+		}
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+/**
+ * 落盘前的格式边界守卫：字段类型/字符集不合规直接拒绝，
+ * 宁可让本次 write 失败也不把不可解析的字节写进状态文件（损坏 = 下次读全丢）。
+ */
+function assertEntry(name: string, e: SolutionEntry): void {
+	if (!/^[\w.-]+$/.test(name)) {
+		throw new Error(`state: 方案名「${name}」含格式外字符，拒绝落盘`);
+	}
+	if (typeof e.version !== "string" || hasQuoteOrControlChar(e.version)) {
+		throw new Error(`state: 方案「${name}」version 必须是不含引号/反斜杠/控制字符的字符串`);
+	}
+	if (typeof e.enabled !== "boolean") {
+		throw new TypeError(`state: 方案「${name}」enabled 必须是布尔值`);
+	}
+	if (typeof e.installedAt !== "number" || !Number.isInteger(e.installedAt)) {
+		throw new TypeError(`state: 方案「${name}」installedAt 必须是整数毫秒时间戳`);
+	}
+}
+
+/** 引号/反斜杠会破坏 version 的双引号定界，控制字符（< 0x20）在 YAML 双引号标量里非法——一律拒绝落盘。 */
+function hasQuoteOrControlChar(s: string): boolean {
+	return /["\\]/.test(s) || [...s].some(ch => ch.charCodeAt(0) < 32);
+}
+
+/** history 行校验用：判断未知值是否为普通对象（非数组/非 null） */
+function isObj(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** 严格解析：逐行匹配固定形状，任何偏差都算损坏（只读回自己写的内容，不做通用 YAML）。 */
+function parseState(text: string): SolutionState {
+	const lines = text.split("\n");
+	if (lines[lines.length - 1] === "") {
+		lines.pop();
+	}
+	if (lines.length === 0) {
+		throw new Error("空文件");
+	}
+	if (lines[0] === "solutions: {}") {
+		if (lines.length !== 1) {
+			throw new Error("「solutions: {}」之后存在多余内容");
+		}
+		return EMPTY;
+	}
+	if (lines[0] !== "solutions:") {
+		throw new Error(`首行应为「solutions:」，实为「${lines[0]}」`);
+	}
+	const solutions: Record<string, SolutionEntry> = {};
+	let i = 1;
+	while (i < lines.length) {
+		const name = /^ {2}([\w.-]+):$/.exec(lines[i])?.[1];
+		if (name === undefined) {
+			throw new Error(`第 ${i + 1} 行应为方案名行，实为「${lines[i]}」`);
+		}
+		const version = /^ {4}version: "(.*)"$/.exec(lines[i + 1] ?? "")?.[1];
+		const enabled = /^ {4}enabled: (true|false)$/.exec(lines[i + 2] ?? "")?.[1];
+		const installedAt = /^ {4}installedAt: (-?\d+)$/.exec(lines[i + 3] ?? "")?.[1];
+		if (version === undefined || enabled === undefined || installedAt === undefined) {
+			throw new Error(`方案「${name}」条目格式不完整或字段损坏`);
+		}
+		const entry: SolutionEntry = { version, enabled: enabled === "true", installedAt: Number(installedAt) };
+		let j = i + 4;
+		// P2-6 可选行（顺序固定：archive 先、trust_state 后；缺即无——P1 时代条目只有四行）
+		const archiveLiteral = /^ {4}archive: "((?:[^"\\]|\\.)*)"$/.exec(lines[j] ?? "")?.[1];
+		if (archiveLiteral !== undefined) {
+			try {
+				const parsed = JSON.parse(JSON.parse(`"${archiveLiteral}"`)) as unknown;
+				if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+					throw new Error("非对象");
+				const a = parsed as Record<string, unknown>;
+				if (typeof a.sha256 !== "string" || typeof a.key_id !== "string" || typeof a.signature !== "object" || a.signature === null)
+					throw new Error("缺 sha256/key_id/signature");
+				entry.archive = { sha256: a.sha256, key_id: a.key_id, signature: a.signature as Record<string, unknown> };
+			}
+			catch {
+				throw new Error(`方案「${name}」archive 行不是合法复验真源 JSON`);
+			}
+			j += 1;
+		}
+		const trust = /^ {4}trust_state: (trusted|untrusted|absent)$/.exec(lines[j] ?? "")?.[1];
+		if (trust !== undefined) {
+			entry.trust_state = trust as "trusted" | "untrusted" | "absent";
+			j += 1;
+		}
+		// P3-2 history：JSON 字符串标量（双串化，同 archive 口径）；非法即损坏
+		const historyLiteral = /^ {4}history: "((?:[^"\\]|\\.)*)"$/.exec(lines[j] ?? "")?.[1];
+		if (historyLiteral !== undefined) {
+			try {
+				const parsed = JSON.parse(JSON.parse(`"${historyLiteral}"`)) as unknown;
+				if (!Array.isArray(parsed) || !parsed.every(x => isObj(x) && typeof x.version === "string" && typeof x.installedAt === "number"))
+					throw new Error("history 非版本时间序数组");
+				entry.history = parsed as Array<{ version: string, installedAt: number }>;
+			}
+			catch {
+				throw new Error(`方案「${name}」history 行不是合法版本时间序 JSON`);
+			}
+			j += 1;
+		}
+		solutions[name] = entry;
+		i = j;
+	}
+	return { solutions };
+}