@actiondock/core 2.19.0 → 2.21.0

package/dist/storage/sqlite-config.d.ts

@@ -1,16 +1,75 @@
-import type { SqliteDriver } from "./types.js";
+import type { ConfigItemDefinition } from "../project/types.js";
+import type { ConfigKeyProvider } from "../security/config-cipher.js";
 import type { Clock } from "./clock.js";
+import { type ConfigSnapshot, type SqliteDriver } from "./types.js";
+/**
+ * 当前版本（3）配置子存储。
+ *
+ * 前置约定：数据库在存储构造前已由 migrations/ 版本调度确保为当前版本
+ * （含 config_encryption 元数据表）。本类不读取或写入 user_version、
+ * 不做 CREATE TABLE、不持有任何历史版本兼容逻辑。
+ *
+ * 行格式：普通值为 JSON 明文，敏感值为 adenc: 密文信封（业务值与历史
+ * 保护声明一同加密）。密文行一经写入永不降级明文；敏感判定命中时存量
+ * 明文由正常写入直接升级为密文。
+ */
 export declare class SqliteConfigStore {
     private statementCache;
     private driver;
     private packageId;
     private dbPath;
     private clock;
-    constructor(driver: SqliteDriver, packageId: string, dbPath: string, clock: Clock);
+    private keyProvider;
+    constructor(driver: SqliteDriver, packageId: string, dbPath: string, clock: Clock, keyProvider: ConfigKeyProvider);
     private getStatement;
+    /** 读取数据库钉住的加密密钥指纹；无行视为元数据缺失。 */
+    private readPinnedKeyId;
+    /**
+     * 读取路径解析密钥：绝不创建密钥，并校验与数据库钉住的指纹一致。
+     *
+     * 密钥缺失、身份不符均抛 CONFIG_ENCRYPTION_ERROR，严禁回退为明文处理。
+     */
+    private resolveKeyForRead;
+    /** 库内是否已存在任何密文行（区分「从未加密」与「元数据被删的损坏态」）。 */
+    private hasAnyEncryptedRow;
+    /**
+     * 敏感写入路径解析密钥（必须在调用方事务内执行）。
+     *
+     * - 已钉住指纹：provider(false) 读取并校验身份一致，确认匹配后再
+     *   provider(true) 确保存储域身份标记已持久化；跨目录导入（恢复/移动
+     *   dataDir 后经 env 密钥继续写入）也会因此留下域身份标记。严禁在校验
+     *   前先 provider(true) 生成新密钥；
+     * - 未钉住指纹：库内存在密文行属损坏状态（元数据被删），拒绝生成替代
+     *   密钥重新钉住；确无密文行则为首次加密，provider(true) 允许创建本地
+     *   密钥并在同一事务内钉住指纹。
+     */
+    private prepareEncryptionMaterial;
+    private decryptEnvelope;
+    private readRow;
+    /**
+     * 单次 SELECT 原子解出业务值与历史保护声明。
+     *
+     * - 键不存在或值为空：返回 undefined（与既有 getConfig 语义一致）；
+     * - 明文行：常规 JSON 解析，快照仅含 value；
+     * - 密文行：严格解密验证后返回 value 与 protection，任何失败均抛错，
+     *   绝不把密文当作普通字符串降级返回。
+     */
+    getConfigSnapshot(key: string): ConfigSnapshot | undefined;
     getConfig<T = unknown>(key: string): T | undefined;
+    getConfigProtection(key: string): readonly ConfigItemDefinition[] | undefined;
     listConfig(): Record<string, unknown>;
-    setConfig(key: string, value: unknown): void;
+    setConfig(key: string, value: unknown, options?: {
+        declarations?: readonly ConfigItemDefinition[];
+    }): void;
+    /**
+     * 写入单个配置键（必须在调用方事务内执行）。
+     *
+     * 加密判定：当前声明判定敏感，或既有行已是密文（一经加密永不降级明文）。
+     * 敏感写入把业务值与合并后的历史保护声明封入同一信封整体加密；声明
+     * 变敏感时存量明文由本次写入直接升级为密文。普通值仍以 JSON 明文存储。
+     */
+    private applyConfigWrite;
+    private upsertRow;
     deleteConfig(key: string): boolean;
     close(): void;
 }

package/dist/storage/sqlite-config.js

@@ -1,15 +1,32 @@
+import { ActionDockError, CONFIG_DECRYPT_FAILED, CONFIG_ENCRYPTION_ERROR } from "../errors.js";
+import { isEncryptedConfigValue } from "../security/config-cipher.js";
+import { decryptConfigEnvelope, encryptConfigEnvelope, mergeProtectionDeclarations } from "./config-value.js";
+import { isSecretConfigKey } from "./mask.js";
 import { safeParseStoredJson } from "./utils.js";
+/**
+ * 当前版本（3）配置子存储。
+ *
+ * 前置约定：数据库在存储构造前已由 migrations/ 版本调度确保为当前版本
+ * （含 config_encryption 元数据表）。本类不读取或写入 user_version、
+ * 不做 CREATE TABLE、不持有任何历史版本兼容逻辑。
+ *
+ * 行格式：普通值为 JSON 明文，敏感值为 adenc: 密文信封（业务值与历史
+ * 保护声明一同加密）。密文行一经写入永不降级明文；敏感判定命中时存量
+ * 明文由正常写入直接升级为密文。
+ */
 export class SqliteConfigStore {
     statementCache = new Map();
     driver;
     packageId;
     dbPath;
     clock;
-    constructor(driver, packageId, dbPath, clock) {
+    keyProvider;
+    constructor(driver, packageId, dbPath, clock, keyProvider) {
         this.driver = driver;
         this.packageId = packageId;
         this.dbPath = dbPath;
         this.clock = clock;
+        this.keyProvider = keyProvider;
     }
     getStatement(sql) {
         let stmt = this.statementCache.get(sql);
@@ -19,24 +36,162 @@ export class SqliteConfigStore {
         }
         return stmt;
     }
-    getConfig(key) {
-        const stmt = this.getStatement("SELECT value_json FROM config WHERE package_id = ? AND key = ?");
-        const row = stmt.get(this.packageId, key);
-        if (!row || row.value_json === undefined || row.value_json === null) {
+    // --- 加密基础设施 ---
+    /** 读取数据库钉住的加密密钥指纹；无行视为元数据缺失。 */
+    readPinnedKeyId() {
+        try {
+            const row = this.getStatement("SELECT key_id FROM config_encryption WHERE id = 1").get();
+            return row?.key_id;
+        }
+        catch (err) {
+            throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config encryption metadata is unreadable for database '${this.dbPath}'`, { dbPath: this.dbPath, reason: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    /**
+     * 读取路径解析密钥：绝不创建密钥，并校验与数据库钉住的指纹一致。
+     *
+     * 密钥缺失、身份不符均抛 CONFIG_ENCRYPTION_ERROR，严禁回退为明文处理。
+     */
+    resolveKeyForRead() {
+        const pinned = this.readPinnedKeyId();
+        if (pinned === undefined) {
+            throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Encrypted config value found in database '${this.dbPath}' but config_encryption metadata is missing`, { dbPath: this.dbPath });
+        }
+        const material = this.keyProvider(false);
+        if (material.id !== pinned) {
+            throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config encryption key does not match the key pinned by database '${this.dbPath}'`, { dbPath: this.dbPath, pinnedKeyId: pinned });
+        }
+        return material;
+    }
+    /** 库内是否已存在任何密文行（区分「从未加密」与「元数据被删的损坏态」）。 */
+    hasAnyEncryptedRow() {
+        const row = this.getStatement("SELECT key FROM config WHERE value_json LIKE 'adenc:%' LIMIT 1").get();
+        return row !== undefined;
+    }
+    /**
+     * 敏感写入路径解析密钥（必须在调用方事务内执行）。
+     *
+     * - 已钉住指纹：provider(false) 读取并校验身份一致，确认匹配后再
+     *   provider(true) 确保存储域身份标记已持久化；跨目录导入（恢复/移动
+     *   dataDir 后经 env 密钥继续写入）也会因此留下域身份标记。严禁在校验
+     *   前先 provider(true) 生成新密钥；
+     * - 未钉住指纹：库内存在密文行属损坏状态（元数据被删），拒绝生成替代
+     *   密钥重新钉住；确无密文行则为首次加密，provider(true) 允许创建本地
+     *   密钥并在同一事务内钉住指纹。
+     */
+    prepareEncryptionMaterial() {
+        const pinned = this.readPinnedKeyId();
+        if (pinned === undefined) {
+            if (this.hasAnyEncryptedRow()) {
+                throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Encrypted config values exist in database '${this.dbPath}' but config_encryption metadata is missing; refusing to pin a replacement key`, { dbPath: this.dbPath });
+            }
+            const material = this.keyProvider(true);
+            this.getStatement("INSERT INTO config_encryption (id, key_id, created_at) VALUES (1, ?, ?)").run(material.id, this.clock.now().toISOString());
+            return material;
+        }
+        const material = this.resolveKeyForRead();
+        const pinnedAgain = this.keyProvider(true);
+        if (pinnedAgain.id !== material.id) {
+            // 防御：提供器在 create 调用中解析出与已校验身份不同的密钥
+            // （如 env 与本地文件不一致），拒绝继续避免写出混合密钥状态
+            throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config encryption key provider resolved inconsistent key identities for database '${this.dbPath}'`, { dbPath: this.dbPath, pinnedKeyId: material.id });
+        }
+        return material;
+    }
+    decryptEnvelope(raw, key) {
+        try {
+            return decryptConfigEnvelope(raw, this.packageId, key, this.resolveKeyForRead());
+        }
+        catch (err) {
+            // 解密异常（认证失败、格式非法、密钥不符）保持原错误码透传，
+            // 仅补充数据库上下文，绝不降级为返回原文。
+            if (err instanceof ActionDockError) {
+                throw err;
+            }
+            throw new ActionDockError(CONFIG_DECRYPT_FAILED, `Decryption of config key '${key}' in package '${this.packageId}' failed unexpectedly`, { dbPath: this.dbPath, key, reason: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    // --- Config 读取 ---
+    readRow(key) {
+        return this.getStatement("SELECT value_json FROM config WHERE package_id = ? AND key = ?").get(this.packageId, key);
+    }
+    /**
+     * 单次 SELECT 原子解出业务值与历史保护声明。
+     *
+     * - 键不存在或值为空：返回 undefined（与既有 getConfig 语义一致）；
+     * - 明文行：常规 JSON 解析，快照仅含 value；
+     * - 密文行：严格解密验证后返回 value 与 protection，任何失败均抛错，
+     *   绝不把密文当作普通字符串降级返回。
+     */
+    getConfigSnapshot(key) {
+        const row = this.readRow(key);
+        const raw = row?.value_json;
+        if (row === undefined || raw === null || raw === undefined) {
             return undefined;
         }
-        return safeParseStoredJson(row.value_json, `config db=${this.dbPath} package=${this.packageId} key=${key}`);
+        if (isEncryptedConfigValue(raw)) {
+            const envelope = this.decryptEnvelope(raw, key);
+            return { value: envelope.value, protection: envelope.protection };
+        }
+        return {
+            value: safeParseStoredJson(raw, `config db=${this.dbPath} package=${this.packageId} key=${key}`),
+        };
+    }
+    getConfig(key) {
+        const snapshot = this.getConfigSnapshot(key);
+        return snapshot?.value;
+    }
+    getConfigProtection(key) {
+        return this.getConfigSnapshot(key)?.protection;
     }
     listConfig() {
         const stmt = this.getStatement("SELECT key, value_json FROM config WHERE package_id = ?");
         const rows = stmt.all(this.packageId);
         const result = {};
         for (const row of rows) {
-            result[row.key] = safeParseStoredJson(row.value_json, `config db=${this.dbPath} package=${this.packageId} key=${row.key}`);
+            if (row.value_json !== null && row.value_json !== undefined && isEncryptedConfigValue(row.value_json)) {
+                const envelope = this.decryptEnvelope(row.value_json, row.key);
+                result[row.key] = envelope.value;
+            }
+            else {
+                result[row.key] = safeParseStoredJson(row.value_json, `config db=${this.dbPath} package=${this.packageId} key=${row.key}`);
+            }
         }
         return result;
     }
-    setConfig(key, value) {
+    // --- Config 写入 ---
+    setConfig(key, value, options) {
+        // 读后写升级场景：事务开始即取得写保留锁，避免并发提交下快照升级 SQLITE_BUSY
+        this.driver.transaction(() => {
+            this.applyConfigWrite(key, value, options?.declarations ?? []);
+        }, "immediate");
+    }
+    /**
+     * 写入单个配置键（必须在调用方事务内执行）。
+     *
+     * 加密判定：当前声明判定敏感，或既有行已是密文（一经加密永不降级明文）。
+     * 敏感写入把业务值与合并后的历史保护声明封入同一信封整体加密；声明
+     * 变敏感时存量明文由本次写入直接升级为密文。普通值仍以 JSON 明文存储。
+     */
+    applyConfigWrite(key, value, declarations) {
+        const currentSensitive = declarations.some((item) => isSecretConfigKey(key, item));
+        const existingRow = this.readRow(key);
+        const existingRaw = existingRow?.value_json;
+        const existingEncrypted = typeof existingRaw === "string" && isEncryptedConfigValue(existingRaw);
+        if (currentSensitive || existingEncrypted) {
+            // 事务内重读既有密文行，合并历史保护声明，防止并发写弱化保护
+            const storedProtection = existingEncrypted
+                ? this.decryptEnvelope(existingRaw, key).protection
+                : [];
+            const protection = mergeProtectionDeclarations(storedProtection, declarations, key);
+            const material = this.prepareEncryptionMaterial();
+            const ciphertext = encryptConfigEnvelope(value, protection, this.packageId, key, material);
+            this.upsertRow(key, ciphertext);
+            return;
+        }
+        this.upsertRow(key, JSON.stringify(value));
+    }
+    upsertRow(key, valJson) {
         const stmt = this.getStatement(`
       INSERT INTO config (package_id, key, value_json, updated_at)
       VALUES (?, ?, ?, ?)
@@ -44,7 +199,6 @@ export class SqliteConfigStore {
         value_json = excluded.value_json,
         updated_at = excluded.updated_at
     `);
-        const valJson = JSON.stringify(value);
         const now = this.clock.now().toISOString();
         stmt.run(this.packageId, key, valJson, now);
     }

package/dist/storage/sqlite-driver.d.ts

@@ -1,6 +1,6 @@
 import type { DatabaseSync } from "node:sqlite";
 import { normalizeSqliteParams } from "./params.js";
-import type { SqliteDriver, SqliteStatement } from "./types.js";
+import type { SqliteDriver, SqliteStatement, SqliteTransactionMode } from "./types.js";
 export { normalizeSqliteParams };
 /**
 
@@ -28,8 +28,11 @@ export declare class NodeSqliteDriver implements SqliteDriver {
     prepare(sql: string): SqliteStatement;
     /**
      * 执行同步事务，严格拒绝并拦截异步 Promise。
+     *
+     * mode 缺省为 deferred（历史行为）；读后写升级场景应传 immediate，
+     * 在事务开始即取得写保留锁，避免并发提交下快照升级失败。
      */
-    transaction<T>(fn: () => T extends PromiseLike<unknown> ? never : T): T;
+    transaction<T>(fn: () => T extends PromiseLike<unknown> ? never : T, mode?: SqliteTransactionMode): T;
     /**
      * 关闭底层数据库连接并释放资源。
      */

package/dist/storage/sqlite-driver.js

@@ -73,10 +73,18 @@ export class NodeSqliteDriver {
     }
     /**
      * 执行同步事务，严格拒绝并拦截异步 Promise。
+     *
+     * mode 缺省为 deferred（历史行为）；读后写升级场景应传 immediate，
+     * 在事务开始即取得写保留锁，避免并发提交下快照升级失败。
      */
-    transaction(fn) {
+    transaction(fn, mode) {
         this.assertOpen();
-        this.db.exec("BEGIN");
+        const beginSql = mode === "immediate"
+            ? "BEGIN IMMEDIATE"
+            : mode === "exclusive"
+                ? "BEGIN EXCLUSIVE"
+                : "BEGIN";
+        this.db.exec(beginSql);
         let result;
         try {
             result = fn();
@@ -102,7 +110,20 @@ export class NodeSqliteDriver {
             }
             throw new ActionDockError(ASYNC_TRANSACTION_UNSUPPORTED, "Async transactions are not allowed in SQLite");
         }
-        this.db.exec("COMMIT");
+        // 提交本身也可能失败（如锁竞争下的 EXCLUSIVE 升级被拒）：必须回滚释放
+        // 事务后重抛原始错误，严禁让连接停留在未决事务内导致后续操作全部失败
+        try {
+            this.db.exec("COMMIT");
+        }
+        catch (err) {
+            try {
+                this.db.exec("ROLLBACK");
+            }
+            catch {
+                // 忽略回滚阶段发生的级联异常
+            }
+            throw err;
+        }
         return result;
     }
     /**

package/dist/storage/sqlite-schema.d.ts

@@ -1,5 +1,23 @@
 import { type SqliteDriver } from "./types.js";
 /**
- * 数据库 Schema 定义、初始化与版本校验。
+ * config_encryption 密钥元数据表 DDL 单一事实源。
+ *
+ * 单行约束（id = 1）钉住数据库的加密密钥指纹。当前版本（3）数据库
+ * 总是携带该表：新库建库时创建，V2 迁移时补齐；无敏感写入时表保持
+ * 空置（不加载或创建任何密钥），首次敏感写入时在同一事务内钉住指纹。
  */
-export declare function initSchema(driver: SqliteDriver, dbPath: string, recoverOrphans: boolean, recoverDeadSessionFn: () => void, cleanExpiredRunsFn: () => void): void;
+export declare const CONFIG_ENCRYPTION_TABLE_DDL = "\n  CREATE TABLE IF NOT EXISTS config_encryption (\n    id INTEGER PRIMARY KEY CHECK (id = 1),\n    key_id TEXT NOT NULL,\n    created_at TEXT NOT NULL\n  );\n";
+/**
+ * 在调用方写事务内创建当前版本完整结构并钉版本号。
+ *
+ * 事务所有权归版本调度器（migrations/index.ts）：锁内重读版本后调用，
+ * 本函数不自建嵌套事务。
+ */
+export declare function createCurrentSchema(driver: SqliteDriver): void;
+/**
+ * 校验当前版本数据库结构完整性：核心表与 runs 关键列必须齐备。
+ *
+ * 声明为当前版本的库缺失关键表或关键列属于损坏（或半升级）状态，
+ * 必须明确拒绝，严禁在打开路径上静默 ALTER / CREATE 修补。
+ */
+export declare function validateCurrentSchema(driver: SqliteDriver, dbPath: string): void;

package/dist/storage/sqlite-schema.js

@@ -1,147 +1,144 @@
-import { existsSync, mkdirSync, chmodSync } from "node:fs";
-import { dirname } from "node:path";
 import { UNSUPPORTED_STORAGE_SCHEMA } from "../errors.js";
 import { STORAGE_SCHEMA_VERSION } from "./types.js";
 /**
- * 数据库 Schema 定义、初始化与版本校验。
+ * config_encryption 密钥元数据表 DDL 单一事实源。
+ *
+ * 单行约束（id = 1）钉住数据库的加密密钥指纹。当前版本（3）数据库
+ * 总是携带该表：新库建库时创建，V2 迁移时补齐；无敏感写入时表保持
+ * 空置（不加载或创建任何密钥），首次敏感写入时在同一事务内钉住指纹。
  */
-export function initSchema(driver, dbPath, recoverOrphans, recoverDeadSessionFn, cleanExpiredRunsFn) {
-    if (dbPath !== ":memory:") {
-        const dir = dirname(dbPath);
-        if (!existsSync(dir)) {
-            try {
-                mkdirSync(dir, { recursive: true, mode: 0o700 });
-                chmodSync(dir, 0o700);
-            }
-            catch {
-                // 忽略系统权限设置失败
-            }
-        }
-    }
-    // 跨进程写并发基线：优先设置 busy_timeout，确保后续 PRAGMA（如 journal_mode = WAL）与表结构初始化在锁争用时能够重试等待
-    driver.exec("PRAGMA busy_timeout = 5000;");
-    driver.exec("PRAGMA journal_mode = WAL;");
-    driver.exec("PRAGMA synchronous = NORMAL;");
-    const versionRes = driver.prepare("PRAGMA user_version;").get();
-    const version = Number(versionRes?.user_version ?? 0);
-    if (version === 0) {
-        driver.transaction(() => {
-            driver.exec(`
-        CREATE TABLE IF NOT EXISTS config (
-          package_id TEXT NOT NULL,
-          key TEXT NOT NULL,
-          value_json TEXT,
-          updated_at TEXT NOT NULL,
-          PRIMARY KEY (package_id, key)
-        );
+export const CONFIG_ENCRYPTION_TABLE_DDL = `
+  CREATE TABLE IF NOT EXISTS config_encryption (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    key_id TEXT NOT NULL,
+    created_at TEXT NOT NULL
+  );
+`;
+/** 当前版本数据库必须存在的核心表集合（缺任一即视为损坏状态）。 */
+const REQUIRED_TABLES = [
+    "config",
+    "state",
+    "runs",
+    "idempotency_keys",
+    "events",
+    "config_encryption",
+];
+/**
+ * 当前版本（3）完整结构 DDL。
+ *
+ * 仅描述当前版本形态：新库一次性创建全部表与索引并落 user_version。
+ * 历史版本的结构差异（如旧 runs 列形态、缺失 events 表）一律由
+ * migrations/v2-to-v3 负责，本模块不保留任何旧版本补齐分支。
+ */
+const CURRENT_SCHEMA_DDL = `
+  CREATE TABLE IF NOT EXISTS config (
+    package_id TEXT NOT NULL,
+    key TEXT NOT NULL,
+    value_json TEXT,
+    updated_at TEXT NOT NULL,
+    PRIMARY KEY (package_id, key)
+  );
 
-        CREATE TABLE IF NOT EXISTS state (
-          package_id TEXT NOT NULL,
-          namespace TEXT NOT NULL,
-          key TEXT NOT NULL,
-          value_json TEXT,
-          updated_at TEXT NOT NULL,
-          expires_at TEXT,
-          PRIMARY KEY (package_id, namespace, key)
-        );
+  CREATE TABLE IF NOT EXISTS state (
+    package_id TEXT NOT NULL,
+    namespace TEXT NOT NULL,
+    key TEXT NOT NULL,
+    value_json TEXT,
+    updated_at TEXT NOT NULL,
+    expires_at TEXT,
+    PRIMARY KEY (package_id, namespace, key)
+  );
 
-        CREATE TABLE IF NOT EXISTS runs (
-          id TEXT PRIMARY KEY,
-          root_run_id TEXT NOT NULL,
-          parent_run_id TEXT,
-          origin_json TEXT,
-          package_id TEXT NOT NULL,
-          package_instance_id TEXT NOT NULL,
-          action_id TEXT NOT NULL,
-          generation_id TEXT NOT NULL,
-          owner_id TEXT NOT NULL,
-          host_session_id TEXT,
-          host_pid INTEGER,
-          heartbeat_at TEXT,
-          status TEXT NOT NULL,
-          input_json TEXT,
-          output_json TEXT,
-          error_json TEXT,
-          started_at TEXT NOT NULL,
-          finished_at TEXT,
-          duration_ms INTEGER
-        );
+  CREATE TABLE IF NOT EXISTS runs (
+    id TEXT PRIMARY KEY,
+    root_run_id TEXT NOT NULL,
+    parent_run_id TEXT,
+    origin_json TEXT,
+    package_id TEXT NOT NULL,
+    package_instance_id TEXT NOT NULL,
+    action_id TEXT NOT NULL,
+    generation_id TEXT NOT NULL,
+    owner_id TEXT NOT NULL,
+    host_session_id TEXT,
+    host_pid INTEGER,
+    heartbeat_at TEXT,
+    status TEXT NOT NULL,
+    input_json TEXT,
+    output_json TEXT,
+    error_json TEXT,
+    started_at TEXT NOT NULL,
+    finished_at TEXT,
+    duration_ms INTEGER
+  );
 
-        CREATE INDEX IF NOT EXISTS idx_runs_action ON runs(package_id, action_id);
-        CREATE INDEX IF NOT EXISTS idx_runs_root ON runs(root_run_id);
-        CREATE INDEX IF NOT EXISTS idx_runs_started ON runs(started_at DESC);
-        CREATE INDEX IF NOT EXISTS idx_runs_host_session ON runs(host_session_id);
-        CREATE INDEX IF NOT EXISTS idx_state_expires ON state(expires_at);
+  CREATE INDEX IF NOT EXISTS idx_runs_action ON runs(package_id, action_id);
+  CREATE INDEX IF NOT EXISTS idx_runs_root ON runs(root_run_id);
+  CREATE INDEX IF NOT EXISTS idx_runs_started ON runs(started_at DESC);
+  CREATE INDEX IF NOT EXISTS idx_runs_host_session ON runs(host_session_id);
+  CREATE INDEX IF NOT EXISTS idx_state_expires ON state(expires_at);
 
-        CREATE TABLE IF NOT EXISTS idempotency_keys (
-          owner_id TEXT NOT NULL,
-          action_ref TEXT NOT NULL,
-          request_id TEXT NOT NULL,
-          input_digest TEXT NOT NULL,
-          run_id TEXT NOT NULL,
-          created_at TEXT NOT NULL,
-          PRIMARY KEY (owner_id, action_ref, request_id)
-        );
-        CREATE INDEX IF NOT EXISTS idx_idemp_run ON idempotency_keys(run_id);
+  CREATE TABLE IF NOT EXISTS idempotency_keys (
+    owner_id TEXT NOT NULL,
+    action_ref TEXT NOT NULL,
+    request_id TEXT NOT NULL,
+    input_digest TEXT NOT NULL,
+    run_id TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    PRIMARY KEY (owner_id, action_ref, request_id)
+  );
+  CREATE INDEX IF NOT EXISTS idx_idemp_run ON idempotency_keys(run_id);
 
-        CREATE TABLE IF NOT EXISTS events (
-          id TEXT PRIMARY KEY,
-          package_id TEXT NOT NULL,
-          event_type TEXT NOT NULL,
-          payload_json TEXT,
-          created_at TEXT NOT NULL
-        );
-        CREATE INDEX IF NOT EXISTS idx_events_type ON events(package_id, event_type);
+  CREATE TABLE IF NOT EXISTS events (
+    id TEXT PRIMARY KEY,
+    package_id TEXT NOT NULL,
+    event_type TEXT NOT NULL,
+    payload_json TEXT,
+    created_at TEXT NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS idx_events_type ON events(package_id, event_type);
 
-        PRAGMA user_version = ${STORAGE_SCHEMA_VERSION};
-      `);
-        });
-    }
-    else if (version !== STORAGE_SCHEMA_VERSION) {
-        const err = new Error(`UNSUPPORTED_STORAGE_SCHEMA: Database schema version ${version} is incompatible (expected ${STORAGE_SCHEMA_VERSION}). Silent upgrade and database overwriting are strictly prohibited.`);
+  ${CONFIG_ENCRYPTION_TABLE_DDL}
+
+  PRAGMA user_version = ${STORAGE_SCHEMA_VERSION};
+`;
+/**
+ * 在调用方写事务内创建当前版本完整结构并钉版本号。
+ *
+ * 事务所有权归版本调度器（migrations/index.ts）：锁内重读版本后调用，
+ * 本函数不自建嵌套事务。
+ */
+export function createCurrentSchema(driver) {
+    driver.exec(CURRENT_SCHEMA_DDL);
+}
+/** 当前版本 runs 表必须存在的迁移新增列（缺失即半升级或损坏状态）。 */
+const REQUIRED_RUNS_COLUMNS = [
+    "origin_json",
+    "host_session_id",
+    "host_pid",
+    "heartbeat_at",
+];
+/**
+ * 校验当前版本数据库结构完整性：核心表与 runs 关键列必须齐备。
+ *
+ * 声明为当前版本的库缺失关键表或关键列属于损坏（或半升级）状态，
+ * 必须明确拒绝，严禁在打开路径上静默 ALTER / CREATE 修补。
+ */
+export function validateCurrentSchema(driver, dbPath) {
+    const rows = driver
+        .prepare("SELECT name FROM sqlite_master WHERE type = 'table'")
+        .all();
+    const present = new Set(rows.map((row) => row.name));
+    const missing = REQUIRED_TABLES.filter((table) => !present.has(table));
+    if (missing.length > 0) {
+        const err = new Error(`UNSUPPORTED_STORAGE_SCHEMA: Database '${dbPath}' declares schema version ${STORAGE_SCHEMA_VERSION} but is missing required tables: ${missing.join(", ")}. The database is in a corrupted or half-upgraded state and silent repair is prohibited.`);
         err.code = UNSUPPORTED_STORAGE_SCHEMA;
         throw err;
     }
-    // 确保存量旧版本数据库补充新增的列或表
-    if (version !== 0) {
-        const columns = driver.prepare("PRAGMA table_info(runs);").all();
-        if (Array.isArray(columns) && !columns.some((c) => c.name === "origin_json")) {
-            driver.exec("ALTER TABLE runs ADD COLUMN origin_json TEXT;");
-        }
-        try {
-            if (Array.isArray(columns) && !columns.some((c) => c.name === "host_session_id")) {
-                driver.exec("ALTER TABLE runs ADD COLUMN host_session_id TEXT;");
-            }
-            // 存活判定依据列：记录所属宿主进程标识与最后一次活跃心跳，旧库以可空列兼容补充
-            if (Array.isArray(columns) && !columns.some((c) => c.name === "host_pid")) {
-                driver.exec("ALTER TABLE runs ADD COLUMN host_pid INTEGER;");
-            }
-            if (Array.isArray(columns) && !columns.some((c) => c.name === "heartbeat_at")) {
-                driver.exec("ALTER TABLE runs ADD COLUMN heartbeat_at TEXT;");
-            }
-        }
-        catch {
-            // 忽略非结构化表或兼容驱动异常
-        }
-        // 确保 events 表存在以支持新增的审计事件仓储
-        try {
-            driver.exec(`
-        CREATE TABLE IF NOT EXISTS events (
-          id TEXT PRIMARY KEY,
-          package_id TEXT NOT NULL,
-          event_type TEXT NOT NULL,
-          payload_json TEXT,
-          created_at TEXT NOT NULL
-        );
-        CREATE INDEX IF NOT EXISTS idx_events_type ON events(package_id, event_type);
-      `);
-        }
-        catch {
-            // 忽略
-        }
-    }
-    if (recoverOrphans) {
-        recoverDeadSessionFn();
-        cleanExpiredRunsFn();
+    const runColumns = new Set(driver.prepare("PRAGMA table_info(runs);").all().map((column) => column.name));
+    const missingColumns = REQUIRED_RUNS_COLUMNS.filter((column) => !runColumns.has(column));
+    if (missingColumns.length > 0) {
+        const err = new Error(`UNSUPPORTED_STORAGE_SCHEMA: Database '${dbPath}' declares schema version ${STORAGE_SCHEMA_VERSION} but table 'runs' is missing required columns: ${missingColumns.join(", ")}. The database is in a corrupted or half-upgraded state and silent repair is prohibited.`);
+        err.code = UNSUPPORTED_STORAGE_SCHEMA;
+        throw err;
     }
 }