@oj-module/cli 0.2.1 → 0.2.5

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

@@ -0,0 +1,182 @@
+// 部署步骤（P1-9，十阶段 stage deploying；R18/R30 前半）：解压 staging 内 web/ 产物树真复制到
+// 站点 web 模块目录（<dist>/modules/<name>/<version>/…，布局与 packages/cli/src/build.ts 产物形态、
+// shell-dist 静态服务约定一致），随后读-改-原子写 upsert modules.json。
+// 站点路径全部 ctx 注入（stagingDir/siteModulesDir/modulesJsonPath）——安装器不硬编码站点布局；
+// fs 依赖同 atomic.ts（globalThis.fs 面，测试注入 node 适配）。
+// D13：modules.json 一切写入经 atomicWriteText——读者（并发 fetch）永不见半截 JSON（AC-P1-12）；
+// 损坏清单拒绝 upsert（避免覆盖丢失他模块条目），宁可 fail-closed。
+// R30：entry/css 路径 POSIX 分隔符序列化（Windows 侧反斜杠统一归一）。
+// R10：integrity 由调用方（P1-10 对验签后包内容重算）传入，本步不计算；缺省回落 manifest.web.integrity
+// （构建器计算值）——integrity 必须基于包内容，防 manifest 与产物错配。
+// entry 浏览器加载验证不在安装器范围（Node import 必假绿——设计 §4.1）：宿主 error boundary 兜底
+// + P2 深检可见，本步只保证落位与清单一致。
+
+import type { FsFace } from "../atomic";
+import type { InstallContext } from "./preflight";
+import { atomicWriteText, fsFace, isMissingPath } from "../atomic";
+
+/**
+ * modules.json 模块条目（对齐 shell 消费面 packages/cli/shell/src/manifest.ts 透传注释与
+ * shell/src/preload.ts HostModule：name/entry/enabled/dependencies/peerRuntime/css 必透传）。
+ * 构建器其余字段（version/chunks）经索引签名原样透传，upsert 不裁剪。
+ */
+export interface ModuleEntry {
+	name: string
+	entry: string
+	enabled: boolean
+	dependencies?: string[]
+	peerRuntime?: string
+	css?: string[]
+	integrity?: string
+	[extra: string]: unknown
+}
+
+/** R30：POSIX 分隔符序列化——反斜杠/正斜杠混合路径统一为 / */
+export function posixPath(p: string): string {
+	return p.split(/[\\/]/).join("/");
+}
+
+function isObj(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** manifest api.deps 的模块依赖键（排除 _platform——平台非 web 模块依赖，P2-15② extras） */
+function apiDepsOf(m: Record<string, unknown>): string[] {
+	const deps = isObj(m.api) && isObj((m.api as Record<string, unknown>).deps) ? (m.api as Record<string, unknown>).deps as Record<string, unknown> : {};
+	return Object.keys(deps).filter(k => k !== "_platform").sort();
+}
+
+/** 归一化条目：entry/css 路径 POSIX 化；其余字段（含构建器 extras）原样透传 */
+function normalizeEntry(entry: ModuleEntry): ModuleEntry {
+	const out: ModuleEntry = { ...entry, entry: posixPath(entry.entry) };
+	if (Array.isArray(entry.css)) {
+		out.css = entry.css.map(c => posixPath(String(c)));
+	}
+	return out;
+}
+
+/**
+ * modules.json 读-modify-原子写 upsert（D13）：同名条目整体替换（位置保持）、其余条目原样保留；
+ * 清单不存在视同空表创建；清单损坏（非合法 JSON / 非数组）拒绝写入并上抛——绝不覆盖。
+ */
+export async function upsertModulesJson(entry: ModuleEntry, opts: { modulesJsonPath: string }): Promise<void> {
+	const f = fsFace();
+	let list: ModuleEntry[] = [];
+	try {
+		list = JSON.parse(new TextDecoder().decode(await f.readFile(opts.modulesJsonPath)));
+	}
+	catch (e) {
+		if (isMissingPath(e)) {
+			list = [];
+		}
+		else if (e instanceof SyntaxError || !Array.isArray(list)) {
+			throw new Error(`modules.json 不是合法 JSON，拒绝 upsert（避免覆盖丢失既有条目，请人工修复后重试）：${String(e)}`);
+		}
+		else {
+			throw e;
+		}
+	}
+	if (!Array.isArray(list)) {
+		throw new TypeError("modules.json 顶层不是数组，拒绝 upsert（避免覆盖丢失既有条目）");
+	}
+	const normalized = normalizeEntry(entry);
+	const idx = list.findIndex(e => isObj(e) && e.name === normalized.name);
+	if (idx === -1) {
+		list.push(normalized);
+	}
+	else {
+		list[idx] = normalized;
+	}
+	await atomicWriteText(opts.modulesJsonPath, `${JSON.stringify(list, null, 2)}\n`);
+}
+
+export interface DeployWebContext extends InstallContext {
+	/** 解压暂存目录（web/ 产物树所在；与 download/verify/extract 同目录接力） */
+	stagingDir: string
+	/** 站点 web 模块目录（<dist>/modules，注入不硬编码） */
+	siteModulesDir: string
+	/** 站点 modules.json 路径（与 siteModulesDir 同属 <dist>） */
+	modulesJsonPath: string
+	/** P1-10 对验签后包内容重算的 sha384（sha384-<base64>，R10）；缺省回落 manifest.web.integrity */
+	integrity?: string
+}
+
+export interface StageResult {
+	stage: "deploying"
+	ok: boolean
+	message: string
+	retryable?: boolean
+}
+
+/** 递归复制目录树（readdir 成功即按目录递归、抛错即按文件复制——FsFace 无 stat 面的最小判别）；迁移服务目录物化复用（B-11） */
+export async function copyTree(src: string, dest: string, f: FsFace): Promise<void> {
+	const names = await f.readdir(src);
+	await f.mkdir(dest, { recursive: true });
+	for (const name of names) {
+		const s = `${src}/${name}`;
+		const d = `${dest}/${name}`;
+		try {
+			await copyTree(s, d, f);
+		}
+		catch {
+			await f.copyFile(s, d);
+		}
+	}
+}
+
+export async function deployWeb(ctx: DeployWebContext): Promise<StageResult> {
+	const m = isObj(ctx.manifest) ? ctx.manifest : {};
+	const web = m.web;
+	if (!isObj(web)) {
+		return { stage: "deploying", ok: true, message: "部署完成：manifest 无 web 段（api-only 方案），零复制零清单变更" };
+	}
+	if (typeof web.entry !== "string" || web.entry === "") {
+		return { stage: "deploying", ok: false, retryable: false, message: "部署失败：web 段存在但 entry 缺失（C2-27：web 段存在时必填）——契约破坏，重试不自愈" };
+	}
+	const f = fsFace();
+	// 包内 web 树即 modules 子树（C2-27 路径空间 = modules/<name>/<version>/…）：
+	// staging/web/modules → 站点 <dist>/modules 一层对齐，不整树套复制（避免 modules/modules 双层嵌套）。
+	try {
+		await copyTree(`${ctx.stagingDir}/web/modules`, ctx.siteModulesDir, f);
+	}
+	catch (e) {
+		return {
+			stage: "deploying",
+			ok: false,
+			retryable: false,
+			message: `部署失败：staging web 产物树（${ctx.stagingDir}/web/modules）不可复制（${String(e)}）——web.entry 已声明而包内 web/modules 缺失属包结构违约（C2-27），重试不自愈`,
+		};
+	}
+	const integrity = typeof ctx.integrity === "string" && ctx.integrity !== ""
+		? ctx.integrity
+		: typeof web.integrity === "string" ? web.integrity : undefined;
+	const entry: ModuleEntry = {
+		name: ctx.name,
+		entry: posixPath(web.entry),
+		enabled: true,
+		// P2-15②（G7 defer-P2 承载）：完整条目 extras——version/dependencies/chunks 补齐
+		// （deployWeb 全新生成 entry，构建器条目不透传的缺口；宿主 HostModule 全字段消费面）
+		version: ctx.version,
+		...(apiDepsOf(m).length > 0 ? { dependencies: apiDepsOf(m) } : {}),
+		chunks: [], // 单 entry 产物无懒加载 chunk（宿主 collectPreloads 消费 `?? []`，字段形状齐备）
+		...(Array.isArray(web.css) ? { css: web.css.map(c => posixPath(String(c))) } : {}),
+		...(integrity !== undefined ? { integrity } : {}),
+		...(typeof m.peerRuntime === "string" ? { peerRuntime: m.peerRuntime } : {}),
+	};
+	try {
+		await upsertModulesJson(entry, { modulesJsonPath: ctx.modulesJsonPath });
+	}
+	catch (e) {
+		return {
+			stage: "deploying",
+			ok: false,
+			retryable: false,
+			message: `部署失败：modules.json upsert 被拒（${String(e)}）——文件已复制、清单未被半写（D13 原子写保证读者无感）`,
+		};
+	}
+	return {
+		stage: "deploying",
+		ok: true,
+		message: `部署完成：staging web/ → ${ctx.siteModulesDir}/，modules.json 已 upsert ${ctx.name}（entry ${entry.entry}${integrity ? `；integrity ${integrity}` : ""}；D13 原子写，读者永不见半截 JSON）`,
+	};
+}

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

@@ -0,0 +1,90 @@
+// 下载步骤（P1-6，十阶段 stage 2 downloading）：S1-2.3 裁决形态——isolate 内 fetch → fs.writeFile。
+// 落盘位 = <staging>/<archive.file>（.staging/<name>-<version>.tgz），与 verify/extract 同目录接力。
+// 失败语义走 StageResult（附录 A downloading：retryable ✓——网络类失败可重试）；契约身份缺失
+// （C2-29，重试不自愈）retryable=false。fetch 面经 ctx 注入（DIP，生产 = 平台 isolate 全局 fetch），
+// fs 同 atomic（globalThis.fs 面）。
+
+import type { InstallContext } from "./preflight";
+import { fsFace } from "../atomic";
+
+/** 最小 fetch 面（结构化：Node fetch/Response 天然满足；测试注入 stub 不真跑网络） */
+export type FetchFace = (url: string) => Promise<{
+	ok: boolean
+	status: number
+	arrayBuffer: () => Promise<ArrayBuffer>
+}>;
+
+export interface DownloadContext extends InstallContext {
+	/** 分发包完整 URL（安装器由市场源 + archive.file 拼装；本步不拼 URL） */
+	archiveUrl: string
+	/** 暂存目录（.staging/）；与 verify/extract 同目录接力（D11 锁前失败清场重跑） */
+	staging: string
+	/** 注入式 fetch 面 */
+	fetch: FetchFace
+}
+
+export interface StageResult {
+	stage: "downloading"
+	ok: boolean
+	message: string
+	retryable?: boolean
+}
+
+/**
+ * 三步共用：从 manifest 提取 archive 身份（C2-29 安全形态守卫，verify/extract 复用）。
+ * file 仅接受 `<name>-<version>.tgz` 安全形态：无路径分隔符（穿越结构性不可能）、
+ * 无前导点、无 `..` 段——这是信任边界（archive 来自分发源），宁可过严不可放行。
+ */
+export function archiveFileOf(manifest: unknown): { ok: true, file: string, archive: Record<string, unknown> } | { ok: false, message: string } {
+	if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
+		return { ok: false, message: "C2-29：manifest 不是键值对象，archive 身份不可得" };
+	}
+	const archive = (manifest as Record<string, unknown>).archive;
+	if (typeof archive !== "object" || archive === null || Array.isArray(archive)) {
+		return { ok: false, message: "C2-29：archive 段缺失或不是键值对象（Form B 真源须含 file/sha256/size）" };
+	}
+	const file = archive.file;
+	if (typeof file !== "string" || !/^[A-Z0-9][\w.-]*$/i.test(file) || file.includes("..")) {
+		return { ok: false, message: `C2-29：archive.file「${String(file)}」缺失或不符安全形态 ^<name>-<version>.tgz$（禁路径分隔符/前导点/.. 穿越段）` };
+	}
+	return { ok: true, file, archive };
+}
+
+export async function download(ctx: DownloadContext): Promise<StageResult> {
+	const arch = archiveFileOf(ctx.manifest);
+	if (!arch.ok) {
+		return { stage: "downloading", ok: false, retryable: false, message: `下载失败：${arch.message}` };
+	}
+	// P2-11 索引投毒加固：archive.file 收紧 <name>-<version>.tgz 逐字（禁异名/异版本/路径拼接；
+	// 此刻 name/version 已过 preflight C2-01/C2-02，均无路径分隔符，逐字等值即排除穿越形态）
+	const expected = `${ctx.name}-${ctx.version}.tgz`;
+	if (arch.file !== expected) {
+		return { stage: "downloading", ok: false, retryable: false, message: `下载失败：archive.file「${arch.file}」须逐字为 <name>-<version>.tgz（「${expected}」，P2-11 索引投毒加固）` };
+	}
+	const dest = `${ctx.staging}/${arch.file}`;
+	try {
+		const res = await ctx.fetch(ctx.archiveUrl);
+		if (!res.ok) {
+			return {
+				stage: "downloading",
+				ok: false,
+				retryable: true,
+				message: `下载失败：分发源返回 HTTP ${res.status}（${ctx.archiveUrl}）——附录 A downloading：请检查网络与市场地址后重试`,
+			};
+		}
+		const bytes = new Uint8Array(await res.arrayBuffer());
+		// P2-11 索引投毒加固：下载后立即比 archive.size（声明在场且为有限数才比对；
+		// 内容级真伪仍由 verify 段 sha256 fail-closed 把关，size 是低成本前置快筛）
+		const declared = arch.archive.size;
+		if (typeof declared === "number" && Number.isFinite(declared) && declared !== bytes.byteLength) {
+			return { stage: "downloading", ok: false, retryable: false, message: `下载失败：分发包 ${bytes.byteLength} 字节与索引声明 archive.size ${declared} 不符——P2-11 索引投毒加固（size 立即比对）` };
+		}
+		const f = fsFace();
+		await f.mkdir(ctx.staging, { recursive: true });
+		await f.writeFile(dest, bytes);
+		return { stage: "downloading", ok: true, message: `下载完成：${arch.file}（${bytes.byteLength} 字节）→ ${dest}` };
+	}
+	catch (e) {
+		return { stage: "downloading", ok: false, retryable: true, message: `下载失败：${String(e)}——附录 A downloading（S1-2.3 fetch→fs.writeFile 范式）` };
+	}
+}

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

@@ -0,0 +1,239 @@
+// 解压步骤（P1-6，十阶段 stage 4 extracting）：R1 zip-slip 防护的 list→validate→extract 三步范式
+// （S1-2.2 裁决：tar 会忠实重建 symlink/hardlink，先列后解是安全必需而非优化）。
+// listing 必须来自 -tvzf verbose 形态（消费方铁律①：非 verbose 裸名首字符撞 l/h 误拒，勿换 -tzf）；
+// 喂 validateTarListing 前先 trim 尾部空行再 split（铁律②：尾随空行=空成员名必拒）。
+// 任一恶意成员 → 全拒且零解压零落盘（附录 A extracting「安装已终止且零落盘」）；校验通过才
+// `tar -xzf -C staging`，解压到 staging 就位即止——版本目录 rename 由 P1-10 落锁段接管。
+// argv 与平台 exec 白名单逐字对齐（S1-2 基座 yaml），不得添加未白名单旗标——安全性由
+// validate 段 + `-C` 限定目标目录承担，而非 tar 旗标。exec 面经 ctx 注入（DIP，测试 stub）。
+
+import type { InstallContext } from "./preflight";
+import { fsFace } from "../atomic";
+import { validateTarListing } from "../tgz-guard";
+import { archiveFileOf } from "./download";
+
+export interface ExecResult {
+	code: number
+	stdout: string
+	stderr: string
+}
+
+export interface ExecFace {
+	/** opts 透传平台 exec.run（timeoutMs 等；0.1.78 共用 opts——缺省 30s 会杀长命令） */
+	run: (argv: string[], opts?: { timeoutMs?: number }) => Promise<ExecResult>
+	/**
+	 * oj 0.1.78 流式形态（P2-13 feature-detect 存在性；缺失回落 exec.run——stage 粒度，进度不增量刷）。
+	 * stdout/stderr 为 AsyncIterable<Uint8Array>（原始字节，UTF-8 切块自管）；exit() 等待退出；
+	 * 超时/超限不抛错只 code=137（v0.1.79 订正）。消费面：migrate 段进度流（h.kill() 主动取消归 P3，G2）。
+	 */
+	spawn?: (argv: string[], opts?: { timeoutMs?: number }) => Promise<ExecSpawnHandle>
+}
+
+/** exec.spawn 句柄（devkit api-manual「exec 流式形态 v0.1.78」；devkit global.d.ts 未收录，此处按契约镜像） */
+export interface ExecSpawnHandle {
+	stdout: AsyncIterable<Uint8Array>
+	stderr: AsyncIterable<Uint8Array>
+	exit: () => Promise<{ code: number }>
+	kill: () => void
+}
+
+export interface ExtractContext extends InstallContext {
+	/** 暂存目录（下载/校验/解压三步同目录接力；亦为解压 -C 目标） */
+	staging: string
+	/** 注入式 exec 面（平台 exec.run；测试 stub 不真跑 tar） */
+	exec: ExecFace
+}
+
+export interface StageResult {
+	stage: "extracting"
+	ok: boolean
+	message: string
+	retryable?: boolean
+}
+
+function isObj(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** tar 列表命令（逐字断言）：-tvzf verbose 形态是 validateTarListing 的输入契约（铁律①） */
+export function buildListCmd(file: string): string[] {
+	return ["tar", "-tvzf", file];
+}
+
+/** tar 解压命令（逐字断言）：-C 限定 staging；对齐 S1-2 白名单 `tar -xzf ${path:archive} -C ${path:dest}` */
+export function buildExtractCmd(file: string, staging: string): string[] {
+	return ["tar", "-xzf", file, "-C", staging];
+}
+
+export async function extract(ctx: ExtractContext): Promise<StageResult> {
+	const arch = archiveFileOf(ctx.manifest);
+	if (!arch.ok) {
+		return { stage: "extracting", ok: false, retryable: false, message: `解压失败：${arch.message}` };
+	}
+	const file = `${ctx.staging}/${arch.file}`;
+	try {
+		// 第一步 list：verbose listing 是安全校验的唯一输入（R1）
+		const listed = await ctx.exec.run(buildListCmd(file));
+		if (listed.code !== 0) {
+			return {
+				stage: "extracting",
+				ok: false,
+				retryable: true,
+				message: `解压失败：tar 列表失败（exit ${listed.code}）：${(listed.stderr || listed.stdout).trim()}（R1 三步范式第一步；附录 A extracting）`,
+			};
+		}
+		// 铁律②：tar 输出恒带尾随换行（可能多个空行），先 trim 尾部空行再 split
+		const lines = listed.stdout.replace(/\n+$/, "").split("\n");
+		// 第二步 validate：任一越界/链接成员即全拒，零解压
+		const v = validateTarListing(lines);
+		if (!v.ok) {
+			return {
+				stage: "extracting",
+				ok: false,
+				retryable: true,
+				message: `解压失败：包内容未通过安全校验（R1：offender「${v.offender}」为越界/链接成员）——零解压零落盘，附录 A extracting：若反复出现请勿使用该分发包`,
+			};
+		}
+		// 第三步 extract：校验通过才落盘；-C staging 就位即止，rename 由 P1-10 落锁段接管
+		const extracted = await ctx.exec.run(buildExtractCmd(file, ctx.staging));
+		if (extracted.code !== 0) {
+			return {
+				stage: "extracting",
+				ok: false,
+				retryable: true,
+				message: `解压失败：tar 解压失败（exit ${extracted.code}）：${(extracted.stderr || extracted.stdout).trim()}（R1 三步范式第三步；附录 A extracting）`,
+			};
+		}
+		await flattenBundleRoot(ctx.staging);
+		const c31 = await checkApiSegment(ctx);
+		if (!c31.ok) {
+			return { stage: "extracting", ok: false, retryable: false, message: c31.message };
+		}
+		return { stage: "extracting", ok: true, message: `解压完成：${lines.length} 个成员 → ${ctx.staging}/（单根已归平，§2.9 布局消费点；C2-31 复核通过；目录 rename 由 P1-10 落锁段接管）` };
+	}
+	catch (e) {
+		return { stage: "extracting", ok: false, retryable: true, message: `解压失败：${String(e)}——附录 A extracting（S1-2 exec.run tar 三步范式）` };
+	}
+}
+
+/** oj 原生模块清单七键白名单（OJ-X 红线：manifest.rs 形态 name/desc/version/config/db/tables/deps） */
+const NATIVE_KEYS = new Set(["name", "desc", "version", "config", "db", "tables", "deps"]);
+
+/**
+ * C2-31 安装期复核纯函数（双端 DRY 于夹具，preflight 同纪律；构建侧同形实现在
+ * packages/cli/src/bundle.ts checkModuleManifest）：包内 oj 原生清单 ↔ C2 Form A 逐项钉住——
+ * name/version 三方一致、desc === summary（构建期映射真源；summary 缺省/多字节/空白边界）、
+ * 七键白名单（白名单外键 = OJ-X 红线，oj 不拒但契约拒）。只验不写：安装期改写 desc 等于
+ * 掩盖上游映射被篡改，必须拒装（附录 B-11 裁决备选的落地形态：bundle 侧 ojm build --bundle
+ * 已写原生清单，安装期复核即映射消费点）。
+ */
+export function checkModuleManifest(
+	c2: unknown,
+	native: unknown,
+	name: string,
+	version: string,
+): { ok: true } | { ok: false, message: string } {
+	if (!isObj(native)) {
+		return { ok: false, message: `包内原生清单不是键值对象（实为 ${native === null ? "null" : Array.isArray(native) ? "数组" : typeof native}）` };
+	}
+	const summary = isObj(c2) && typeof c2.summary === "string" ? c2.summary : undefined;
+	if (summary === undefined || summary.trim() === "") {
+		return { ok: false, message: "C2 manifest summary 缺省或空白——desc 映射无真源（C2-31/C2-04）" };
+	}
+	const desc = native.desc;
+	if (typeof desc !== "string" || desc.trim() === "") {
+		return { ok: false, message: "包内原生清单 desc 缺失或空白（oj Manifest 必填字段，serve 装配即失败）——C2-31" };
+	}
+	if (desc !== summary) {
+		return { ok: false, message: "包内原生清单 desc 与 C2 summary 不一致（构建期映射被篡改或上游不一致，拒装）——C2-31" };
+	}
+	if (native.name !== name) {
+		return { ok: false, message: `包内原生清单 name「${String(native.name)}」与安装身份「${name}」不一致——C2-31` };
+	}
+	if (native.version !== version) {
+		return { ok: false, message: `包内原生清单 version「${String(native.version)}」与安装身份「${version}」不一致——C2-31` };
+	}
+	const extra = Object.keys(native).filter(k => !NATIVE_KEYS.has(k));
+	if (extra.length > 0) {
+		return { ok: false, message: `包内原生清单含白名单外键「${extra.join("、")}」（七键 = name/desc/version/config/db/tables/deps，OJ-X 红线）——C2-31` };
+	}
+	return { ok: true };
+}
+
+/**
+ * C2-31 安装期复核接线（extracting 段收口）：manifest 声明 api 段而包内 api/<name>-<version>/
+ * 缺失 = 结构违约；包内 api 模块目录在则必复核其原生清单（web-only 包无 api 段 → 跳过）。
+ * yaml 解析走 oj 全局（market/api.ts 同款），解析失败按复核不通过处理（fail-closed）。
+ */
+async function checkApiSegment(ctx: ExtractContext): Promise<{ ok: true } | { ok: false, message: string }> {
+	const modDir = `${ctx.staging}/api/${ctx.name}-${ctx.version}`;
+	let inner: string[];
+	try {
+		inner = await fsFace().readdir(modDir);
+	}
+	catch {
+		const declared = isObj(ctx.manifest) && ctx.manifest.api !== undefined;
+		if (!declared) {
+			return { ok: true }; // web-only 方案：无 api 段，migrate 段同步跳过
+		}
+		return { ok: false, message: `解压复核失败：manifest 声明 api 段而包内 api/${ctx.name}-${ctx.version}/ 缺失（§2.9 结构违约）——C2-31` };
+	}
+	if (!inner.includes("manifest.yaml")) {
+		return { ok: false, message: `解压复核失败：api/${ctx.name}-${ctx.version}/ 缺 manifest.yaml（oj 原生清单，oj build 产物必带）——C2-31` };
+	}
+	const g = globalThis as { yaml?: { parse: (text: string) => Promise<unknown> } };
+	let native: unknown;
+	try {
+		native = await g.yaml!.parse(new TextDecoder().decode(await fsFace().readFile(`${modDir}/manifest.yaml`)));
+	}
+	catch (e) {
+		return { ok: false, message: `解压复核失败：api/${ctx.name}-${ctx.version}/manifest.yaml 不可解析（${String(e)}）——C2-31` };
+	}
+	return checkModuleManifest(ctx.manifest, native, ctx.name, ctx.version);
+}
+
+/**
+ * 单根归平（契约 §2.9 布局消费点，P1-13 真机冒烟实测缺此步——附录 B-10）：`ojm build --bundle`
+ * 产物是 `<name>-<version>/` 单根 tgz，`tar -xzf -C staging` 后内容嵌在一层目录里，而安装器
+ * 全链消费扁平 staging（verifyTarget/deployWeb 读 `${staging}/manifest.yaml`，lockCommit 把
+ * staging 整体 rename 成版本目录）。归平规则：顶层「以 manifest.yaml 为首层标记」的目录 = 包根，
+ * 内容上提一层；标记不匹配（api/、web/、archive 文件）一律不动——不猜布局，宁可下游可读失败。
+ * 幂等：flat 布局无匹配目录即空操作；market file 源预解包（manifestOfUpload）与本步骤同调此函数，
+ * 二次解压重建的单根目录再次被归平。
+ */
+export async function flattenBundleRoot(staging: string): Promise<void> {
+	const f = fsFace();
+	let names: string[];
+	try {
+		names = await f.readdir(staging);
+	}
+	catch {
+		return; // staging 不可列（不存在等）交由下游可读失败
+	}
+	for (const name of names) {
+		const root = `${staging}/${name}`;
+		let inner: string[];
+		try {
+			inner = await f.readdir(root); // readdir 失败 = 普通文件（archive 等），跳过
+		}
+		catch {
+			continue;
+		}
+		if (!inner.includes("manifest.yaml")) {
+			continue;
+		}
+		for (const item of inner) {
+			const dest = `${staging}/${item}`;
+			try {
+				await f.rename(`${root}/${item}`, dest);
+			}
+			catch {
+				// 目标已在（market file 源预解包 manifestOfUpload 先归平过同一 staging，重装/重试
+				// 时上次产物尚在——附录 B-10）：staging 是安装器私有无价值暂存，先清后搬
+				await f.remove(dest, { recursive: true, force: true });
+				await f.rename(`${root}/${item}`, dest);
+			}
+		}
+		await f.remove(root, { recursive: true });
+	}
+}