@oj-module/cli 0.2.6 → 0.2.14

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

@@ -5,7 +5,7 @@
 // 参数化 insert，与 audit.ts 同纪律（值不拼字符串）。
 
 // db 为 oj isolate 注入全局（同模板 service 层惯例，installer.ts 同款；测试由夹具装 globalThis.db）
-declare const db: { exec: (sql: string, params: unknown[]) => Promise<unknown> };
+declare const db: { exec: (sql: string, params: unknown[]) => Promise<unknown>, table: (name: string) => any };
 
 export interface HistoryRow {
 	solution: string
@@ -20,10 +20,15 @@ export interface HistoryRow {
 /** 守卫式 insert：表不存在/写失败一律静默（留痕失败不影响主流程） */
 export async function recordHistory(row: HistoryRow): Promise<void> {
 	try {
-		await db.exec(
-			"insert into market_history (solution, version, action, status, operator, message, created_at) values (?, ?, ?, ?, ?, ?, ?)",
-			[row.solution, row.version, row.action, row.status, row.operator, row.message, Math.floor(Date.now() / 1000)],
-		);
+		await db.table("market_history").insert({
+			solution: row.solution,
+			version: row.version,
+			action: row.action,
+			status: row.status,
+			operator: row.operator,
+			message: row.message,
+			created_at: Math.floor(Date.now() / 1000),
+		}).run();
 	}
 	catch {
 		// 表不存在（市场方案未装）或写失败：静默跳过，不阻断主流程

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

@@ -14,7 +14,7 @@
 // setEnabled 四处同写（D12/AC-P1-6）：锁摘除/恢复 + sidecar + sys_solution_route.enabled +
 // modules.json enabled；启用从 sidecar 摘除前记录恢复版本。db 为 isolate 全局（同模板 service 层）。
 
-import type { OpEntry } from "../_shared/service/audit";
+import type { OpEntry } from "../_shared/service/infra/audit";
 import type { TaskLock } from "./lock";
 import type { StateStore } from "./state";
 import type { FetchFace } from "./steps/download";
@@ -22,7 +22,7 @@ import type { ExecFace } from "./steps/extract";
 import type { SettingDecl, SolutionDecl, SolutionSnapshot } from "./steps/register";
 import type { ReloadFace } from "./steps/reload";
 import type { InstallContext, InstallStage, StageResult, TaskRecord, TaskStatus } from "./types";
-import { auditOp } from "../_shared/service/audit";
+import { auditOp } from "../_shared/service/infra/audit";
 import { atomicWriteText, fsFace, randomId } from "./atomic";
 import { recordHistory } from "./history";
 import { acquireTaskLock, commitLockEntry, readLock, writeLock } from "./lock";
@@ -40,7 +40,7 @@ import { appendAnonymousPaths, bumpInstallSeq } from "./text-edit";
 import { createTrustStore } from "./trust";
 
 // db/http 为 oj isolate 注入全局（同模板 service 层惯例，register.ts/audit.ts 同款；测试由夹具装 globalThis.db）
-declare const db: { exec: (sql: string, params: unknown[]) => Promise<unknown> };
+declare const db: { exec: (sql: string, params: unknown[]) => Promise<unknown>, table: (name: string) => any };
 
 export type { InstallContext, InstallStage, StageResult, TaskRecord, TaskStatus };
 
@@ -1039,7 +1039,7 @@ export async function setEnabled(input: SetEnabledInput): Promise<{ ok: boolean,
 	}
 	// ③ route 表 enabled（生命周期开关，非注册内容直写，D10 不适用）
 	try {
-		await db.exec("update sys_solution_route set enabled = ? where module = ?", [enabled ? 1 : 0, name]);
+		await db.table("sys_solution_route").update({ enabled: enabled ? 1 : 0 }).where({ field: "module", op: "eq", value: name }).run();
 	}
 	catch (e) {
 		audit(false, `route enabled 写失败：${String(e)}`);

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

@@ -101,7 +101,7 @@ export function sha384Bytes(data: Uint8Array): Uint8Array {
 	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 });
+	const w = Array.from({ length: 80 }, () => [0, 0] as [number, number]);
 	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)];

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

@@ -39,7 +39,7 @@ export function archiveFileOf(manifest: unknown): { ok: true, file: string, arch
 	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;
+	const archive = (manifest as Record<string, unknown>).archive as Record<string, unknown>;
 	if (typeof archive !== "object" || archive === null || Array.isArray(archive)) {
 		return { ok: false, message: "C2-29：archive 段缺失或不是键值对象（Form B 真源须含 file/sha256/size）" };
 	}

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

@@ -122,10 +122,13 @@ const NATIVE_KEYS = new Set(["name", "desc", "version", "config", "db", "tables"
 /**
  * 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
- * 已写原生清单，安装期复核即映射消费点）。
+ * name/version 三方一致、七键白名单（白名单外键 = OJ-X 红线，oj 不拒但契约拒）。
+ * 只验不写：安装期改写原生清单等于掩盖上游不一致。
+ *
+ * 变更（2026-10-21）：**desc === summary 的等值校验已移除**。该等值要求把「构建期映射」
+ * 当成安装期契约，于是 fixture/手写包只要 desc 与 summary 有一字之差就整包装不上——
+ * 校验成本远高于它拦下的风险（desc 只是模块描述文本，非安全边界）。现只保留
+ * 「summary 必填（C2-04）」与「desc 必填非空（oj 启动装配面）」两项。
  */
 export function checkModuleManifest(
 	c2: unknown,
@@ -138,15 +141,12 @@ export function checkModuleManifest(
 	}
 	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）" };
+		return { ok: false, message: "C2 manifest summary 缺省或空白（C2-04 必填字段）——C2-31" };
 	}
 	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` };
 	}

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

@@ -8,9 +8,9 @@
 // 是其既有语义，本文件不越界代改）。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";
+import type { SolutionManifest } from "../../_shared/service/domain/solution-perms";
+import { upsertSolutionPerms } from "../../_shared/service/domain/solution-perms";
+import { auditOp } from "../../_shared/service/infra/audit";
 
 export interface RouteDecl {
 	path: string
@@ -76,19 +76,19 @@ function firstSeg(path: string): string {
  * 让位须走卸载），自占排除（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 rows = await db.table("sys_solution_route").select(["path"]).where({ field: "module", op: "ne", value: module }).all() 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 old = await db.table(table).select([col]).where({ field: "module", op: "eq", value: module }).where({ field: "deprecated", op: "eq", value: 0 }).all() 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]);
+			await db.table(table).update({ deprecated: 1 }).where({ field: col, op: "eq", value: k }).run();
 			gone.push(k);
 		}
 	}
@@ -122,36 +122,64 @@ export async function registerSolution(decl: SolutionDecl): Promise<RegisterResu
 		// 设置项 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[];
+			const exists = await db.table("sys_setting").select(["key"]).where({ field: "key", op: "eq", value: s.key }).all() 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],
-				);
+				await db.table("sys_setting").update({
+					module: decl.module,
+					group: s.group,
+					type: s.type,
+					default_value: s.default_value ?? null,
+					label_key: s.label_key ?? null,
+					group_label_key: s.group_label_key ?? null,
+					options: s.options ?? null,
+					secret: s.secret ? 1 : 0,
+					deprecated: 0,
+					update_time: Date.now(),
+				}).where({ field: "key", op: "eq", value: s.key }).run();
 			}
 			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()],
-				);
+				await db.table("sys_setting").insert({
+					key: s.key,
+					module: decl.module,
+					group: s.group,
+					type: s.type,
+					value: s.value ?? s.default_value ?? null,
+					default_value: s.default_value ?? null,
+					label_key: s.label_key ?? null,
+					group_label_key: s.group_label_key ?? null,
+					options: s.options ?? null,
+					secret: s.secret ? 1 : 0,
+					update_time: Date.now(),
+					deprecated: 0,
+				}).run();
 			}
 		}
 		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[];
+			const exists = await db.table("sys_solution_route").select(["path"]).where({ field: "path", op: "eq", value: r.path }).all() 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],
-				);
+				await db.table("sys_solution_route").update({
+					module: decl.module,
+					category: r.category,
+					order: r.order,
+					title_key: r.title_key ?? null,
+					required_permission: r.required_permission ?? null,
+					deprecated: 0,
+				}).where({ field: "path", op: "eq", value: r.path }).run();
 			}
 			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],
-				);
+				await db.table("sys_solution_route").insert({
+					path: r.path,
+					module: decl.module,
+					category: r.category,
+					order: r.order,
+					title_key: r.title_key ?? null,
+					required_permission: r.required_permission ?? null,
+					deprecated: 0,
+					enabled: 1,
+				}).run();
 			}
 		}
 		const routeDeps = await deprecateGone("sys_solution_route", "path", decl.module, new Set(routes.map(r => r.path)));
@@ -177,10 +205,10 @@ export async function registerSolution(decl: SolutionDecl): Promise<RegisterResu
 }
 
 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();
+	const routes = (await db.table("sys_solution_route").select(["path"]).where({ field: "module", op: "eq", value: name }).where({ field: "deprecated", op: "eq", value: 0 }).all() as Array<{ path: string }>).map(r => String(r.path)).sort();
+	const settings = (await db.table("sys_setting").select(["key"]).where({ field: "module", op: "eq", value: name }).where({ field: "deprecated", op: "eq", value: 0 }).all() as Array<{ key: string }>).map(r => String(r.key)).sort();
+	const roles = (await db.table("sys_role").select(["name"]).where({ field: "module", op: "eq", value: name }).where({ field: "deprecated", op: "eq", value: 0 }).all() as Array<{ name: string }>).map(r => String(r.name)).sort();
+	const permissions = (await db.table("sys_permission").select(["code"]).where({ field: "module", op: "eq", value: name }).where({ field: "deprecated", op: "eq", value: 0 }).all() as Array<{ code: string }>).map(r => String(r.code)).sort();
 	if (routes.length + settings.length + roles.length + permissions.length === 0) {
 		return null;
 	}
@@ -195,7 +223,7 @@ 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 }>;
+		const rows = await db.table(table).distinct().select(["module"]).where({ field: "deprecated", op: "eq", value: 0 }).all() as Array<{ module: string }>;
 		for (const r of rows) {
 			names.add(String(r.module));
 		}

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

@@ -1,4 +1,4 @@
-import { auditOp } from "../_shared/service/audit";
+import { auditOp } from "../_shared/service/infra/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 依赖，严格解析）。

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

@@ -7,23 +7,23 @@
 // 任一步失败返回 {ok:false, message}（与 setEnabled 同纪律）；部分残差由 admin 重试或重装自愈。
 // SQL 全部参数化（与 audit.ts / setEnabled 同纪律，值不拼字符串）。
 
-import type { OpEntry } from "../_shared/service/audit";
+import type { OpEntry } from "../_shared/service/infra/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 { uninstallSolution } from "../_shared/service/domain/solution-perms";
+import { invalidateAllUsers } from "../_shared/service/infra/access";
+import { auditOp } from "../_shared/service/infra/audit";
 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.query 同返回行数组） */
+	table: (name: string) => any
+	/** 目录自省（v0.1.82）：当前库全部/前缀匹配的表名（方言无关；前缀 %/_ 由引擎转义） */
+	listTables: (prefix?: string) => Promise<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>
+	tx: <T>(fn: (t: { table: (name: string) => any }) => Promise<T>) => Promise<T>
 };
 
 function isObj(v: unknown): v is Record<string, unknown> {
@@ -60,44 +60,13 @@ function manifestTables(yamlText: string): string[] {
 	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}_%`;
+/** 模块 slug 规范化（连字符→下划线）作表前缀；db.listTables 内部按字面量前缀匹配（自动转义 %/_），无需手拼通配 */
+export function moduleTablePrefix(name: string): string {
+	return `${name.replace(/-/g, "_")}_`;
 }
 
 /** 收集需保留的业务表（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 {
@@ -108,16 +77,17 @@ export async function collectRetainedTables(name: string, manifestPath: string):
 	catch {
 		// manifest 缺失（api-only 方案）→ 仅前缀兜底
 	}
-	// ② 前缀兜底：扫描当前库匹配模块前缀的表，覆盖未声明场景
+	// ② 前缀兜底：db.listTables（v0.1.82，方言无关，前缀转义引擎做）枚举当前库匹配模块前缀的
+	//    实际表，覆盖未声明场景。listTables 已只返回存在的表，故前缀命中的候选天然存在。
 	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);
+		for (const t of await db.listTables(moduleTablePrefix(name)))
+			candidates.add(t);
 	}
 	catch {
 		// 兜底扫描失败不阻断卸载
 	}
+	// 仅回传实际存在的表（manifest 声明的表若物理不存在则不回传）
+	const existing = new Set(await db.listTables());
 	return [...candidates].filter(t => existing.has(t));
 }
 
@@ -155,15 +125,18 @@ export interface UninstallResult {
 /** 计算卸载影响面（角色数 + 持有这些角色的用户数） */
 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 roles = await db.table("sys_role").select(["name"]).where({ field: "module", op: "eq", value: name }).all() 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;
+		// 构造器（v0.1.82）：count(distinct) 聚合一行返回，不受 LIMIT 钳制——
+		// 旧 distinct().all().length 因顶层隐式 LIMIT（默认 100）/ 显式 clamp（max_limit 默认 1000）
+		// 在受影响用户 >1000 时静默漏算（今天就有正确性风险，须尽快迁移）。
+		const rows = await db.table("sys_user_role")
+			.select([{ fn: "count", distinct: true, field: "user_id", as: "c" }])
+			.where({ field: "role_name", op: "in", value: roleNames })
+			.all() as Array<{ c: number }>;
+		affectedUsers = rows[0]?.c ?? 0;
 	}
 	return { name, affectedRoles: roleNames.length, affectedUsers };
 }
@@ -202,7 +175,7 @@ export async function runUninstall(input: UninstallInput): Promise<UninstallResu
 	// 边界。任一步失败 → 整段回滚（无角色/权限/路由半残），锁不摘（fail-closed：模块仍挂载、可重试或重装自愈）。
 	try {
 		await db.tx(async (t) => {
-			await t.exec("delete from sys_solution_route where module = ?", [name]);
+			await t.table("sys_solution_route").where({ field: "module", op: "eq", value: name }).delete().run();
 			await uninstallSolution(name, t);
 		});
 	}
@@ -213,7 +186,7 @@ export async function runUninstall(input: UninstallInput): Promise<UninstallResu
 
 	// ② sidecar 删条目（patch 值 null = 删除该方案键）
 	try {
-		await input.state.write({ solutions: { [name]: null } });
+		await input.state.write({ solutions: { [name]: null } } as unknown as Parameters<typeof input.state.write>[0]);
 	}
 	catch (e) {
 		audit(false, `sidecar 写失败：${String(e)}`);

package/templates/api/src/_platform/_lifecycle/verify-checks.ts

@@ -206,12 +206,12 @@ export async function diffWebIntegrity(
 		const bytes = await fsFace().readFile(`${distRoot}/${me.entry}`);
 		const actual = `sha384-${sha384(new Uint8Array(bytes))}`;
 		if (actual !== me.integrity) {
-			items.push({ id: "web", severity: "error", subject: me.entry, advise_key: "lifecycle.verify.web.integrity_mismatch" });
+			items.push({ id: "web", severity: "error", subject: me.entry ?? "*", advise_key: "lifecycle.verify.web.integrity_mismatch" });
 		}
 	}
 	catch {
 		// 资产缺失（web 入口未落位或路径变更）——info 非阻断（路由可达性已另测）
-		items.push({ id: "web", severity: "info", subject: me.entry, advise_key: "lifecycle.verify.web.asset_missing" });
+		items.push({ id: "web", severity: "info", subject: me.entry ?? "*", advise_key: "lifecycle.verify.web.asset_missing" });
 	}
 	return items;
 }

package/templates/api/src/_platform/_shared/service/{contacts.ts → domain/contacts.ts}

@@ -2,8 +2,6 @@
 // 目录红线：只出 id/username/display_name——不含 email/avatar/roles（防低权账号拖走全员邮箱喂钓鱼，安全评审 P2）；
 // 详情端点才给 email/avatar。默认排除 is_forbidden=1（AC1-23：管理域仍可见，目录与管理分离）。
 // keyword≥2、LIKE 转义复用 query.ts；solutions 同 isolate import searchContacts 直调，无 HTTP 往返（AC1-25）。
-import { likePattern } from "./query";
-
 export interface ContactRow {
 	id: number
 	username: string
@@ -14,22 +12,31 @@ const DEFAULT_LIMIT = 200;
 const MAX_LIMIT = 200;
 
 export async function searchContacts(keyword: unknown, opts: { limit?: unknown } = {}): Promise<ContactRow[]> {
-	const pattern = likePattern(keyword); // <2 字符在此抛 400（AC1-22）
+	// 长度红线（默认 2~64，越界 400）——与 query.ts likePattern 同口径；contains 自动转义 %/_/!，无需手写 ESCAPE。
+	const kw = String(keyword ?? "").trim();
+	if (kw.length < 2 || kw.length > 64)
+		throw Object.assign(new Error(kw.length < 2 ? "keyword too short (min 2)" : "keyword too long (max 64)"), { status: 400 });
 	const rawLimit = Number.parseInt(String(opts.limit ?? ""), 10);
 	const limit = Number.isFinite(rawLimit) && rawLimit >= 1 ? Math.min(MAX_LIMIT, rawLimit) : DEFAULT_LIMIT;
-	return await db.query(
-		`select id, username, display_name from users
-		 where is_forbidden = 0 and (username like ? escape '!' or display_name like ? escape '!')
-		 order by username limit ?`,
-		[pattern, pattern, limit],
-	) as ContactRow[];
+	// 构造器（v0.1.81）：模糊搜索走语义 op contains（自动转义 + 包 %），OR 用条件树 or，方言无关。
+	return await db.table("users")
+		.select(["id", "username", "display_name"])
+		.where({ field: "is_forbidden", op: "eq", value: 0 })
+		.where({ or: [
+			{ field: "username", op: "contains", value: kw },
+			{ field: "display_name", op: "contains", value: kw },
+		] })
+		.orderBy([{ field: "username", dir: "asc" }])
+		.limit(limit)
+		.all() as unknown as ContactRow[];
 }
 
 export async function contactDetail(id: number): Promise<Record<string, unknown>> {
-	const rows = await db.query(
-		"select id, username, display_name, email, avatar_base64 from users where id = ? and is_forbidden = 0",
-		[id],
-	);
+	const rows = await db.table("users")
+		.select(["id", "username", "display_name", "email", "avatar_base64"])
+		.where({ field: "id", op: "eq", value: id })
+		.where({ field: "is_forbidden", op: "eq", value: 0 })
+		.all();
 	if (!rows[0])
 		throw Object.assign(new Error("contact not found"), { status: 404 });
 	return rows[0] as Record<string, unknown>;

package/templates/api/src/_platform/_shared/service/{roles.ts → domain/roles.ts}

@@ -2,8 +2,8 @@
 // 规则锚：custom 机器名强制（AC1-17）、builtin 角色绑定/删除硬拒（AC1-19）、占用禁删（AC1-20）、
 // 绑定调整 = 紧急吊销出口（AC1-30，写后按持有者失效判权缓存）、写审计 await recordOp（AC1-28 关键路径）。
 // 判权本身不经过这里——调用 handler 先过 assertSystemAdmin（H2，管理类端点）。
-import { invalidateUser } from "./access";
-import { recordOp } from "./audit";
+import { invalidateUser } from "../infra/access";
+import { recordOp } from "../infra/audit";
 
 export interface RoleRow {
 	name: string
@@ -35,7 +35,7 @@ const CUSTOM_NAME = /^custom\.[a-z0-9][a-z0-9-]*$/;
 const RESERVED = new Set(["superadmin", "admin", "editor", "viewer"]);
 
 async function assertNotBuiltin(roleName: string): Promise<void> {
-	const rows = await db.query("select builtin from sys_role where name = ?", [roleName]);
+	const rows = await db.table("sys_role").select(["builtin"]).where({ field: "name", op: "eq", value: roleName }).all();
 	if (!rows[0])
 		fail(404, `role not found: ${roleName}`);
 	if (Number((rows[0] as { builtin: unknown }).builtin) === 1)
@@ -45,9 +45,8 @@ async function assertNotBuiltin(roleName: string): Promise<void> {
 async function assertCodesExist(codes: string[]): Promise<void> {
 	if (!codes.length)
 		return;
-	const marks = codes.map(() => "?").join(",");
-	const rows = await db.query(`select code from sys_permission where code in (${marks})`, codes);
-	const known = new Set(rows.map((r: { code: string }) => r.code));
+	const rows = await db.table("sys_permission").select(["code"]).where({ field: "code", op: "in", value: codes }).all();
+	const known = new Set(rows.map(r => (r as { code: string }).code));
 	const unknown = codes.filter(c => !known.has(c));
 	if (unknown.length)
 		fail(400, `unknown permission codes: ${unknown.join(", ")}`);
@@ -55,15 +54,15 @@ async function assertCodesExist(codes: string[]): Promise<void> {
 
 /** 绑定/删除写后按持有者逐人失效判权缓存（D10 撤销即强退的 service 级出口）。 */
 async function invalidateHolders(roleName: string): Promise<void> {
-	const rows = await db.query("select user_id from sys_user_role where role_name = ?", [roleName]);
+	const rows = await db.table("sys_user_role").select(["user_id"]).where({ field: "role_name", op: "eq", value: roleName }).all();
 	for (const r of rows as Array<{ user_id: number }>)
 		invalidateUser(Number(r.user_id));
 }
 
 export async function listRoles(): Promise<RoleRow[]> {
-	const roles = await db.query("select * from sys_role order by name") as Array<Record<string, unknown>>;
-	const holders = await db.query("select role_name, count(*) as c from sys_user_role group by role_name") as Array<{ role_name: string, c: number }>;
-	const binds = await db.query("select role_name, permission_code from sys_role_permission order by permission_code") as Array<{ role_name: string, permission_code: string }>;
+	const roles = await db.table("sys_role").select(["name", "module", "title", "description", "builtin", "deprecated"]).orderBy([{ field: "name" }]).all() as Array<Record<string, unknown>>;
+	const holders = await db.table("sys_user_role").select(["role_name", { fn: "count", as: "c" }]).groupBy(["role_name"]).all() as Array<{ role_name: string, c: number }>;
+	const binds = await db.table("sys_role_permission").select(["role_name", "permission_code"]).orderBy([{ field: "permission_code" }]).all() as Array<{ role_name: string, permission_code: string }>;
 	const holderMap = new Map(holders.map(h => [h.role_name, Number(h.c)]));
 	const bindMap = new Map<string, string[]>();
 	for (const b of binds)
@@ -81,7 +80,7 @@ export async function listRoles(): Promise<RoleRow[]> {
 }
 
 export async function listPermissions(): Promise<PermissionRow[]> {
-	const rows = await db.query("select * from sys_permission order by code") as Array<Record<string, unknown>>;
+	const rows = await db.table("sys_permission").select(["code", "module", "title_key", "deprecated"]).orderBy([{ field: "code" }]).all() as Array<Record<string, unknown>>;
 	return rows.map(r => ({
 		code: String(r.code),
 		module: String(r.module),
@@ -97,9 +96,9 @@ export async function createRole(input: { name: string, title: string, permissio
 	const permissions = [...new Set((input.permissions ?? []).map(String))];
 	await assertCodesExist(permissions);
 	await db.tx(async (t) => {
-		await t.exec("insert into sys_role (name, module, title, builtin, deprecated) values (?, 'custom', ?, 0, 0)", [name, String(input.title ?? "")]);
+		await t.table("sys_role").insert({ name, module: "custom", title: String(input.title ?? ""), builtin: 0, deprecated: 0 }).run();
 		for (const code of permissions)
-			await t.exec("insert into sys_role_permission (role_name, permission_code) values (?, ?)", [name, code]);
+			await t.table("sys_role_permission").insert({ role_name: name, permission_code: code }).run();
 	});
 	await recordOp({ action: "role.create", module: "framework", target: name, detail: { title: String(input.title ?? ""), permissions } });
 	return { name, module: "custom" };
@@ -109,12 +108,12 @@ export async function updateBindings(roleName: string, codes: string[]): Promise
 	await assertNotBuiltin(roleName);
 	const next = [...new Set(codes.map(String))];
 	await assertCodesExist(next);
-	const before = (await db.query("select permission_code from sys_role_permission where role_name = ?", [roleName])) as Array<{ permission_code: string }>;
+	const before = (await db.table("sys_role_permission").select(["permission_code"]).where({ field: "role_name", op: "eq", value: roleName }).all()) as Array<{ permission_code: string }>;
 	const beforeSet = new Set(before.map(b => b.permission_code));
 	await db.tx(async (t) => {
-		await t.exec("delete from sys_role_permission where role_name = ?", [roleName]);
+		await t.table("sys_role_permission").where({ field: "role_name", op: "eq", value: roleName }).delete().run();
 		for (const code of next)
-			await t.exec("insert into sys_role_permission (role_name, permission_code) values (?, ?)", [roleName, code]);
+			await t.table("sys_role_permission").insert({ role_name: roleName, permission_code: code }).run();
 	});
 	await invalidateHolders(roleName);
 	const added = next.filter(c => !beforeSet.has(c));
@@ -124,13 +123,13 @@ export async function updateBindings(roleName: string, codes: string[]): Promise
 
 export async function deleteRole(roleName: string): Promise<void> {
 	await assertNotBuiltin(roleName);
-	const holders = await db.query("select count(*) as c from sys_user_role where role_name = ?", [roleName]);
+	const holders = await db.table("sys_user_role").select([{ fn: "count", as: "c" }]).where({ field: "role_name", op: "eq", value: roleName }).all();
 	const n = Number((holders[0] as { c: unknown }).c);
 	if (n > 0)
 		fail(409, `role has ${n} holder(s)`, { holders: n });
 	await db.tx(async (t) => {
-		await t.exec("delete from sys_role_permission where role_name = ?", [roleName]);
-		await t.exec("delete from sys_role where name = ?", [roleName]);
+		await t.table("sys_role_permission").where({ field: "role_name", op: "eq", value: roleName }).delete().run();
+		await t.table("sys_role").where({ field: "name", op: "eq", value: roleName }).delete().run();
 	});
 	await invalidateHolders(roleName);
 	await recordOp({ action: "role.delete", module: "framework", target: roleName });